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

流控降级异常类BlockException

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

  • 流控异常:FlowException
  • 降级异常:DegradeException
  • 系统保护异常:SystemException

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

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 count) throws BlockException
  • public static Entry entry(String name, EntryType type) throws BlockException
  • public static Entry entry(String name, EntryType type, int count) throws BlockException
  • public static Entry entry(String name, EntryType type, int count, Object... args) throws BlockException

其中资源名为传入的name

传入Method对象定义方法资源

  • public static Entry entry(Method method) throws BlockException
  • public static Entry entry(Method method, int count) 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 count, Object... args) throws BlockException

其中的参数解释如下。

参数名 类型 解释 默认值
count int 本次资源调用请求的token数目。 1
type EntryType 用于区分该资源是入口流量(EntryType.IN)还是出口流量(EntryType.OUT)。注意系统规则只对IN埋点生效,同时控制台展示的监控应用总流量也仅统计IN的流量。 EntryType.OUT
args Object[] 传入的参数,用于热点参数限流。

返回值类型:

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

更多使用请参见定义资源

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的变换。