文档

常用类及其方法

更新时间:

本文为您介绍流控降级常用类和方法。

流控降级异常类BlockException

在Sentinel中所有流控降级相关的异常都是异常类BlockException的子类:

  • 流控异常:FlowException
  • 降级异常:DegradeException
  • 系统保护异常:SystemException
  • 热点参数限流异常:ParamFlowException

您可以通过以下方法判断是否为流控降级异常:

BlockException.isBlockException(Throwable t);

资源定义类SphU / SphO

SphUSphO是两个常用的用于资源定义的工具类。其中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

其中的参数解释如下。

参数名类型解释默认值
entryTypeEntryType资源调用的流量类型,是入口流量(IN)、出口流量(OUT)、内部调用(INTERNAL)。注意系统自适应保护只对IN类型生效。EntryType.OUT
resourceTypeInt资源调用分类,如 Web/RPC/DB_SQL。COMMON(0)
batchCountInt本次资源调用请求的Token数目(即算作几次调用)。1
argsObject[]传入的参数,用于热点参数限流。

返回值类型:

  • 普通的资源定义返回Entry对象,代表本次资源的调用。
  • 异步资源定义返回AsyncEntry对象,代表本次异步资源的调用。

更多使用请参见定义资源

托管资源定义类SentinelWrapper

说明 SentinelWrapper在Java SDK 1.8.0及以上版本引入。

SentinelWrapper用于定义托管执行的资源埋点。SentinelWrapperSphU/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
参数名类型解释默认值
funcCallable<R>用户要执行的函数,结果会体现在返回值上。无(必传)
fallbackFunctionCheckedFunction<Throwable, R>fallback函数,当出现异常时通过这个函数生成fallback结果。
entryTypeEntryType资源调用的流量类型,是入口流量(IN)、出口流量(OUT)、内部调用(INTERNAL)。注意系统自适应保护只对IN类型生效。EntryType.OUT
resourceTypeInt资源调用分类,如 Web/RPC/DB_SQL。COMMON(0)
argsObject[]传入的参数,用于热点参数限流。

Entry

Entry对象代表某一次资源调用,通过SphUSphO定义资源后会返回此对象。主要方法:

  • 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

如果用户通过SphUSphO手动定义资源,则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,即生成的调用链路上下文对象。

说明 ContextUtil.enter(xxx)方法仅在调用链路入口处生效,即仅在当前线程的初次调用生效,后面再调用不会覆盖当前线程的调用链路,直到exit。Context存于ThreadLocal中,因此切换线程时可能会丢掉,如果需要跨线程使用可以结合runOnContext方法使用。

流控规则中若选择“流控方式”为“链路”方式,则入口资源名即为上面的contextName

退出调用链(清空上下文)

  • public static void exit():该方法用于退出调用链,清理当前线程的上下文。

获取当前线程的调用链上下文

  • public static Context getContext():获取当前线程的调用链路上下文对象。

在某个调用链上下文中执行代码

  • public static void runOnContext(Context context, Runnable f):常用于异步调用链路中context的变换。