Sentinel GO API 使用指南

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。

通用配置項加載政策和配置項請參考

配置方式使用文檔

示例代碼：

import (
    sentinel "github.com/alibaba/sentinel-golang/api"
)

func initSentinel() {
    err := sentinel.Init(confPath)
    if err != nil {
        // 初始化 Sentinel 失敗
    }
}      

注意：必須成功調用 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 示例：

import (
    sentinel "github.com/alibaba/sentinel-golang/api"
)

// Entry 方法用于埋點
e, b := sentinel.Entry("your-resource-name", sentinel.WithTrafficType(base.Inbound))
if b != nil {
    // 請求被流控，可以從 BlockError 中擷取限流詳情
    // block 後不需要進行 Exit()
} else {
    // 請求可以通過，在此處編寫您的業務邏輯
    // 務必保證業務邏輯結束後 Exit
    e.Exit()
}      

若該次調用被拒絕，則 Entry API 會傳回 BlockError 代表被 Sentinel 限流。BlockError 提供了限流原因以及觸發的規則等資訊，可以友善開發者擷取相關資訊進行記錄和處理。

規則配置

寫死方式

Sentinel 支援原始的寫死方式加載規則，可以通過各個子產品的

LoadRules(rules)

函數加載規則。以流控規則為例：

_, err = flow.LoadRules([]*flow.Rule{
    {
        Resource:               "some-test",
        Threshold:              10,
        TokenCalculateStrategy: flow.Direct,
        ControlBehavior:        flow.Reject,
    },
})
if err != nil {
    // 加載規則失敗，進行相關處理
}      

動态資料源

Sentinel 提供動态資料源接口進行擴充，使用者可以通過動态檔案、etcd、consul、nacos 等配置中心來動态地配置規則。