Sentinel GO API 使用指南

工具与资源中心
帮助开发者更加高效的工作，提供围绕开发者全生命周期的工具与资源
https://developer.aliyun.com/...

API 使用指南

用户接入使用 Sentinel Go (后文均用 Sentinel 表示 Sentinel Go) 主要需要需要以下几步：

1. 对 Sentinel 的运行环境进行相关配置并初始化。API 接口使用细节可以参考：配置方式
2. 埋点（定义资源），该步骤主要是确定系统中有哪些资源需要防护，资源定义可参考：新手指南
3. 配置规则，该步骤主要是为每个资源都配置具体的规则，规则的配置可参考：新手指南以及各个模块的使用文档。

4. 编写资源防护的入口和出口代码。释放方式可参考：新手指南

   通用配置及初始化

   使用 Sentinel 需要在应用启动时对 Sentinel 运行环境进行相关配置并触发初始化。api 包下提供如下函数：
   • InitDefault()：从环境变量指定的配置文件以及环境变量中读取相应配置来初始化 Sentinel，若环境变量不存在则使用默认值。
   • Init(configPath string)：从给定的 YAML 文件中读取相应配置来初始化 Sentinel。
   • InitWithConfig(confEntity config.Entity): 用户硬编码配置对象config.Entity来初始化Sentinel。
   通用配置项加载策略和配置项请参考 配置方式使用文档
   示例代码：

5. import (
6. sentinel "github.com/alibaba/sentinel-golang/api"
7. )
8. func initSentinel() {
9. err := sentinel.Init(confPath)
10. if err != nil {
11. // 初始化 Sentinel 失败
12. }

13. }
    注意：必须成功调用 Sentinel 的初始化函数以后再调用埋点 API。

    埋点(定义资源)

    使用 Sentinel 的 Entry API 将业务逻辑封装起来，这一步称为“埋点”。每个埋点都有一个资源名称（resource），代表触发了这个资源的调用或访问。
    埋点 API 位于 api 包中：
    • Entry(resource string, opts ...Option) (base.SentinelEntry, base.BlockError)
    其中 resource 代表埋点资源名，opts 代表埋点配置。这里需要注意的是，返回值参数列表的第一个和第二个参数是互斥的，也就是说，如果Entry执行pass，那么Sentinel会返回(base.SentinelEntry, nil)；如果Entry执行blocked，那么Sentinel会返回(nil, base.BlockError)。
    目前支持以下埋点配置：
    • WithTrafficType(entryType base.TrafficType)：标记该埋点资源的流量类型，其中 Inbound 代表入口流量，Outbound 代表出口流量。若不指定，默认为 Outbound。
    • WithResourceType(resourceType base.ResourceType)：标记该埋点资源的分类。
    • WithAcquireCount(acquireCount uint32)：标记每次触发该埋点计为几次调用（可以理解为 batch count）。若不指定，默认为 1。
    • WithArgs(args ...interface{})：埋点携带的参数列表，为热点参数统计预留。
    • WithSlotChain(chain *base.SlotChain)：埋点执行的检查的slotchain，若不指定，默认使用全局slotchain
    埋点 API 示例：

14. import (
15. sentinel "github.com/alibaba/sentinel-golang/api"
16. )
17. // Entry 方法用于埋点
18. e, b := sentinel.Entry("your-resource-name", sentinel.WithTrafficType(base.Inbound))
19. if b != nil {
20. // 请求被流控，可以从 BlockError 中获取限流详情
21. // block 后不需要进行 Exit()
22. } else {
23. // 请求可以通过，在此处编写您的业务逻辑
24. // 务必保证业务逻辑结束后 Exit
25. e.Exit()

26. }
    若该次调用被拒绝，则 Entry API 会返回 BlockError 代表被 Sentinel 限流。BlockError 提供了限流原因以及触发的规则等信息，可以方便开发者获取相关信息进行记录和处理。

    规则配置

    硬编码方式

    Sentinel 支持原始的硬编码方式加载规则，可以通过各个模块的 LoadRules(rules) 函数加载规则。以流控规则为例：

27. _, err = flow.LoadRules([]*flow.Rule{
28. {
29. Resource: "some-test",
30. Threshold: 10,
31. TokenCalculateStrategy: flow.Direct,
32. ControlBehavior: flow.Reject,
33. },
34. })
35. if err != nil {
36. // 加载规则失败，进行相关处理

37. }

    动态数据源

    Sentinel 提供动态数据源接口进行扩展，用户可以通过动态文件、etcd、consul、nacos 等配置中心来动态地配置规则。