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

流控降级异常类 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 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 的变换。