流控降級異常類BlockException

在Sentinel中所有流控降級相關的異常都是異常類BlockException的子類：

• 流控異常：FlowException

• 降級異常：DegradeException

• 系統保護異常：SystemException

• 熱點參數限流異常：ParamFlowException

您可以通過以下方法判斷是否為流控降級異常：

BlockException.isBlockException(Throwable t);

資源定義類SphU / SphO

SphU和SphO是兩個常用的用于資源定義的工具類。其中SphU以try-catch的形式定義資源，而SphO以if-else的形式定義資源。

SphU類包含以下幾組靜態方法：

傳入資源名定義資源：

• public static Entry entry(String name) throws BlockException

• public static Entry entry(String name, int batchCount) throws BlockException

• public static Entry entry(String name, EntryType type) throws BlockException

• public static Entry entry(String name, EntryType type, int batchCount) throws BlockException

• public static Entry entry(String name, EntryType type, int batchCount, Object... args) throws BlockException

其中資源名為傳入的name。

傳入Method對象定義方法資源：

• public static Entry entry(Method method) throws BlockException

• public static Entry entry(Method method, int batchCount) throws BlockException

• public static Entry entry(Method method, EntryType type) throws BlockException

• public static Entry entry(Method method, EntryType type, int count) throws BlockException

• public static Entry entry(Method method, EntryType type, int count, Object... args) throws BlockException

其中資源名將從傳入的Method對象解析，格式為類名:方法簽名，如com.alibaba.csp.sentinel.demo.DemoService:foo(java.lang.String)。

異步資源定義：

• public static AsyncEntry asyncEntry(String name) throws BlockException

• public static AsyncEntry asyncEntry(String name, EntryType type) throws BlockException

• public static AsyncEntry asyncEntry(String name, EntryType type, int batchCount, Object... args) throws BlockException

其中的參數解釋如下。

返回值類型：

• 普通的資源定義返回Entry對象，代表本次資源的調用。

• 異步資源定義返回AsyncEntry對象，代表本次異步資源的調用。

更多使用請參見定義資源。

托管資源定義類SentinelWrapper

SentinelWrapper用于定義托管執行的資源埋點。SentinelWrapper與SphU/SphO的不同在于SentinelWrapper需要您提供要執行的函數，并托管執行（與@SentinelResource注解方式類似），可以支持自動重試、超時熔斷等機制。SentinelWrapper的主要函數有兩個：

• execute：在出現異常（包括被限流）時會直接拋出異常。

• executeWithFallback：可以接受一個fallback函數來處理異常，返回正常的結果。

托管資源定義類SentinelWrapper如下：

• public static <R> R execute(Callable<R> func, String resource, EntryType trafficType, int resourceType) throws Exception

• public static <R> R execute(Callable<R> func, String resource, EntryType trafficType, int resourceType, Object[] args) throws Exception

• public static <R> R executeWithFallback(Callable<R> func, CheckedFunction<Throwable, R> fallbackFunction, String resource, EntryType trafficType) throws Exception

• public static <R> R executeWithFallback(Callable<R> func, CheckedFunction<Throwable, R> fallbackFunction, String resource, EntryType trafficType, int resourceType) throws Exception

• public static <R> R executeWithFallback(Callable<R> func, CheckedFunction<Throwable, R> fallbackFunction, String resource, EntryType trafficType, int resourceType, Object[] args) throws Exception

Entry

Entry對象代表某一次資源調用，通過SphU或SphO定義資源后會返回此對象。主要方法：

• public void exit() throws ErrorEntryFreeException：表示資源調用結束，需要與entry方法成對出現。

異常描述：

• ErrorEntryFreeException：當前資源調用exit與entry不匹配會拋出此異常。資源的entry與exit必須成對出現。

業務異常記錄類Tracer

業務異常記錄類Tracer用于記錄業務異常。相關方法：

• public static void trace(Throwable e)：記錄業務異常（非BlockException異常）。

• public static void trace(Throwable e, int count)：記錄業務異常，異常數目為傳入的count。

如果用戶通過SphU或SphO手動定義資源，則Sentinel不能感知上層業務的異常，需要手動調用Tracer.trace(ex)來記錄業務異常，否則對應的異常不會統計到Sentinel異常計數中。

注解方式定義資源支持自動統計業務異常，無需手動調用Tracer.trace(ex)來記錄業務異常。Web Servlet適配、Dubbo適配也會自動統計業務異常，無需手動統計。

上下文工具類ContextUtil

相關方法：

標識進入調用鏈入口（上下文）：

以下靜態方法用于標識調用鏈路入口，用于區分不同的調用鏈路：

• public static Context enter(String contextName)

• public static Context enter(String contextName, String origin)

其中contextName代表調用鏈路入口名稱（上下文名稱），origin代表調用來源名稱。默認調用來源為空。返回值類型為Context，即生成的調用鏈路上下文對象。

流控規則中若選擇“流控方式”為“鏈路”方式，則入口資源名即為上面的contextName。

退出調用鏈（清空上下文）：

public static void exit()：該方法用于退出調用鏈，清理當前線程的上下文。

獲取當前線程的調用鏈上下文：

public static Context getContext()：獲取當前線程的調用鏈路上下文對象。

在某個調用鏈上下文中執行代碼：

public static void runOnContext(Context context, Runnable f)：常用于異步調用鏈路中context的變換。