去年排查过一个挺有意思的限流故障规则明明配好了压测数据也上去了但限流就是不生效。最后翻到代码层面问题出在一个特别容易被忽略的细节上——资源埋点的位置在一个子线程里Context 已经断了。那次经历让我彻底明白Sentinel 的四个核心概念——资源、规则、Slot 链、Context——根本不是零散知识而是同一条流量治理流水线上的四道工序。这篇文章我会把这条流水线从头拆一遍适合刚开始接触 Sentinel 的 Java 开发者也适合那些已经用过一段时间、但遇到“规则为什么不生效”只能靠猜的同行。读完之后你至少能自己照着思路定位大部分常见问题。1. 从限流失效说起先建立四个概念的全局坐标当时那个场景是典型的微服务调用链。服务 A 通过线程池并发调用服务 B 的下单接口我们给下单接口配了一条调用链限流规则从服务 A 入口进入、目标资源“createOrder”、单机 QPS 阈值 50。压测时服务 B 的吞吐量一路冲到五千多限流规则一次都没触发。排查到最后结论是线程池把父线程的 Context 弄丢了。Sentinel 的规则判断完全建立在 Context 所维护的调用树之上树断了链路模式限流自然成了空摆设。这个案例我会在最后一章完整复盘这里先把它当引子把四个概念的整体关系摆出来。资源你要保护的那段代码路径比如一个接口、一个 RPC 方法、一个数据库操作先“标记”出来。规则针对资源配置的判定标准比如 QPS 超过多少就拒绝、RT 超过多少就熔断。Slot 链每个资源在被调用时都会走一遍的流水线上面的每个 Slot 负责一种能力规则检查只是其中一个环节。Context一次调用链的上下文它把当前请求经过的入口、资源、节点、调用方来源串在一起Slot 链上所有判断都需要依赖它。这四个概念在请求处理时的实际顺序是请求进来Context 被创建或复用接着代码里调用资源入口资源触发对应的 Slot 链Slot 链上的每个节点依次执行流量控制、熔断降级、系统保护等规则在各自节点完成判断。如果命中规则抛BlockException业务代码负责捕获并走降级逻辑。一句话概括资源定义“保护谁”规则定义“怎么判”Slot 链定义“按什么顺序判”Context 定义“判的时候能用到哪些现场信息”。下面逐个展开。2. 资源规则的作用对象也是第一道门2.1 两种埋点方式与 EntryType 的选择Sentinel 里所有治理动作都围绕资源展开。资源可以是任意一段代码你把它用入口方法包起来它就成了被管控的对象。官方常说的“埋点”本质上就是这件事调用资源入口进入 Slot 链。埋点有两种主流写法。第一种用SphU.entry它会在被限流时抛出异常适合对返回结果敏感、需要精细降级的场景try (Entry entry SphU.entry(createOrder)) { // 受保护的业务逻辑 return createOrder(); } catch (BlockException ex) { // 被限流或被熔断走降级逻辑 return fallback(); }第二种用SphO.entry返回布尔值适合做开关或封装时用if (SphO.entry(createOrder)) { try { return createOrder(); } finally { SphO.exit(); } } else { return fallback(); }这里有个经常被忽略的参数EntryType。入口类型分IN和OUT分别代表请求进入系统的方向和调用外部依赖的方向。Web 接口、RPC 服务端入口通常是IN向外发起 RPC、数据库访问通常是OUT。这个参数会直接影响系统保护规则里对“入口流量”和“出口流量”的统计口径如果你把出口调用标成了IN系统保护里的阈值计算就会混入不该算的数据。try (Entry entry SphU.entry(createOrder, EntryType.IN, 1)) { // ... }第三个参数count是本次请求占用的资源数量默认传 1。大多数场景下都用默认值只有在做批量扣减或权重控制时才会改它。2.2 资源名规范稳定、唯一、可读资源名是最容易被随意对待、却对结果影响最大的东西。它有几个硬性要求第一稳定。资源名不能带请求参数不能带时间戳。常见错误是把用户 ID 拼进资源名比如queryUser:12345、queryUser:12346。这样一来每个用户一个资源名每个资源的统计量被拆得七零八落你配置在queryUser:12345上的规则根本覆盖不到queryUser:12346。第二唯一。同名资源会被ClusterBuilderSlot映射到同一个统计节点如果两个完全不相关的业务路径共用一个资源名它们的流量会被合并统计限流就会互相误伤。反过来同一个接口如果每次请求资源名写得不完全一致规则又永远对不上。第三可读。资源名不仅是内部标识也是你排查问题时的索引。推荐用“模块:接口:动作”这种语义化的格式比如order:create,pay:callback。配合日志和监控面板一眼能看出流量集中在哪个环节。2.3 高频翻车的三个资源定义细节我见过不少生产事故根因都出在资源定义这一步。第一个是资源名拼接了可变参数。之前某团队把订单号拼进了资源名结果压测阶段 QPS 一秒破干规则却一条都没触发因为每个资源只有极小流量。排查时一看规则列表全是类似getOrder:ORD123456789这种名字你根本没法配规则。解决思路很简单资源名保持接口语义订单号作为参数传下去做热点参数限流而不是改变资源身份。第二个是同一个线程里嵌套资源时退出顺序乱了。资源是可以嵌套的先进入父资源再进入子资源退出时必须严格遵守先进后出的顺序。如果用 try-with-resources 或 try-finally 管理顺序通常不会错但如果你在子资源里忘了exitThreadLocal 里的 Context 就一直挂着父资源可能导致后续链路统计异常甚至请求结束后内存里残留节点。第三个是毫秒级统计场景下选了过粗的资源粒度。比如整个网关接口作为一个资源底下包含多个后端调用其中只有一个数据库查询是慢的。熔断规则配置在网关资源上必然导致整个接口被熔断大量本来健康的请求跟着遭殃。这类场景应该把资源粒度下沉到具体后端调用或者把慢调用单独抽成资源别让一颗老鼠屎坏了一锅汤。3. 规则从配置到生效的完整路径3.1 规则家族成员与各自的核心参数Sentinel 的规则不止大家最常用的限流。完整的规则家族我建议你用一张表记住规则类型核心参数作用典型场景流量控制规则resource、count、gradeQPS/线程数、strategy直连/关联/链路、controlBehavior直接拒绝/预热/匀速排队限制单机或集群维度通过的流量保护下游接口不被打垮熔断降级规则resource、gradeRT/异常比例/异常数、count、timeWindow当指标持续超阈值时熔断窗口内快速失败下游响应变慢、错误率飙升时兜底系统保护规则highestCpuUsage、avgRt、maxThread、qps从系统维度做全局保护防止整机雪崩服务器负载过高时主动限流授权规则resource、limitApp、白名单/黑名单按调用来源做黑白名单控制禁止某些来源调用核心接口热点参数规则resource、paramIdx、paramFlowItemList对同一个资源里的特定参数值做差异化控制某个热搜商品单独限流不影响其他商品流量控制规则里还有一个容易弄混的字段controlBehavior。默认是直接拒绝适合大多数场景预热模式适合刚启动的接口或有缓存预热的系统让流量缓慢增长匀速排队模式适合削峰填谷系统会控制请求通过的间隔而不是瞬间拒绝多余流量。熔断降级规则里不同的grade类型对应不同的计数方式。按 RT 熔断时count是最大耗时按异常比例熔断时count是 0 到 1 的比例值按异常数熔断时count是异常次数。配置前先想清楚你要防的是“慢”还是“错”两者对应的阈值语义完全不同。3.2 规则从配置到检查的完整路径规则配置好之后它在内存里的组织方式和执行时的查找路径很多人没有概念。拿流量控制规则举例ListFlowRule rules new ArrayList(); FlowRule rule new FlowRule(createOrder); rule.setGrade(RuleConstant.FLOW_GRADE_QPS); rule.setCount(100); rule.setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_DEFAULT); rules.add(rule); FlowRuleManager.loadRules(rules);FlowRuleManager负责保存当前生效的流量规则列表执行时FlowSlot中的FlowRuleChecker先从FlowRuleManager.getRules()里拿到与当前资源匹配的规则再根据规则里的策略解析出对应的检查器。直连、关联、链路这三种strategy各自对应不同的检查逻辑。把规则加载到内存之后还有一个生产环境绕不开的问题规则怎么动态下发。loadRules只是把规则推到本地内存部署多机时不可能手动去每台机器敲一遍。这里需要接入动态数据源扩展让规则从配置中心推送到各个节点的FlowRuleManager。配置中心一更新各机器上的内存规则跟着变不需要重启服务。扩展包里针对流量、熔断、系统、授权等规则都提供了对应的数据源实现比如把 Nacos、Redis 或本地文件作为配置源。接入后你只需要维护配置中心里那份规则 JSON客户端会定时拉取或接收推送。规则格式是 JSON字段名也和规则类字段一一对应配置中心里写错了字段启动时不一定会报错但规则会加载失败或解析成默认值这点在落地时要格外留意。3.3 多条规则同时在场时谁先谁后同一个资源上可以同时配置多种规则比如既配了流量控制又配了熔断降级还配了系统保护。当所有规则都满足时判断顺序是固定轮不到的因为每种规则居住在 Slot 链的不同节点上。规则之间通过 Slot 链的位置天然形成了优先级系统保护规则先于单资源流量控制规则因为系统级保护关心的是整机存活优先保证宿主不挂流量控制规则先于熔断降级规则因为流量先被控制住了熔断才有意义否则熔断判断的统计值已经被限流失真了。同一个类型下的多条规则判断时是“或”关系只要命中任意一条规则请求就会被拒绝。比如你给某个资源配了两条流量控制规则一条阈值 100一条阈值 50那实际生效的阈值是 50。这不算 bug是设计预期但配置时要意识到这一点别把两套团队的历史规则叠在一个资源上否则你看到的限流阈值会和单条规则的数值对不上。4. Slot 链责任链模式撑起的流量流水线4.1 责任链模式为什么不用 if-else 大函数Slot 链在代码上是一条双向链表每个 Slot 节点实现了统一的ProcessorSlot接口。请求进入资源时从链头开始依次调用每个节点的entry方法节点处理完自己的逻辑后通过fireEntry把请求交给下一个节点退出资源时再从链尾依次执行每个节点的exit方法。如果把这些判断全部写进一个大类随着功能增多这个类会膨胀成几千行的巨型 if-else 树林。责任链模式则把每一项能力拆成独立 Slot新增能力时只需要在链上插入一个新节点不动已有节点职责边界清楚也方便通过扩展机制做定制。这个设计直接决定了一件事Slot 在链上的顺序是语义的一部分。统计要先于策略否则策略判断时拿不到最新数据系统保护要先于单资源限流否则系统已经濒危了还在放单资源流量。4.2 默认链路里每个 Slot 都在忙什么默认链路通常有九个 Slot各自分工如下Slot职责依赖数据NodeSelectorSlot为资源创建或获取 DefaultNode构建调用树Context、DefaultNodeClusterBuilderSlot为资源创建或获取 ClusterNode做跨 Context 聚合ResourceWrapper、ClusterNodeLogSlot记录异常日志BlockException 处理信息StatisticSlot统计维度数据包括通过数、拒绝数、耗时等滑动窗口 MetricBucketParamFlowSlot热点参数限流ParamFlowRule、请求参数SystemSlot系统自适应保护CPU、Load、QPS、RT 等系统指标AuthoritySlot授权规则黑白名单来源应用名FlowSlot流量控制规则滑动窗口统计DegradeSlot熔断降级规则滑动窗口统计和熔断状态这个顺序不是随意排的。NodeSelectorSlot 在第一位因为后面所有统计和判断都需要先在调用树上找到自己的节点StatisticSlot 在策略判断之前因为 FlowSlot 和 DegradeSlot 拿到的 QPS、RT 都是从统计节点里读出来的。SystemSlot 排在 FlowSlot 前面保证系统级别保护先于单资源保护。LogSlot 排得比较靠前它主要处理异常日志对判断逻辑本身没有依赖。理解每个 Slot 的位置之后你再看到“规则不生效”第一步就能判断问题出在链路前半段还是后半段。比如授权规则和流量控制规则都不生效而系统保护规则看起来正常那大概率问题出在校验前的 Context 和 Node 构建上。4.3 滑动窗口Slot 链判断依赖的数据底座FlowSlot 判断 QPS 时不是直接数当前一秒进来多少请求而是通过滑动窗口算法计算一个窗口周期内的速率。滑动窗口的实现核心是一个环形数组每个元素是一个时间窗口桶窗口按固定时长切片随着时间推移不断复用和覆盖。// 简化思路按时间算出桶下标再判断桶是否过期 long timeId currentTimeMillis / windowLengthInMs; int index (int) (timeId % array.length()); WindowWrapMetricBucket old array.get(index); if (old null || old.windowStart() intervalInMs currentTimeMillis) { WindowWrapMetricBucket newWrap new WindowWrap(windowLengthInMs, currentTimeMillis, new MetricBucket()); array.set(index, newWrap); } MetricBucket bucket old null ? newWrap.value() : old.value(); bucket.add(QpsPass, count);每个时间窗格子里维护着通过的请求数、被拒绝的请求数、总耗时等指标。判断当前是否有窗口过期时看一眼windowStart intervalInMs是否小于等于当前时间过期就新建桶覆盖否则就复用旧桶继续累加。这套机制的好处是统计精度和时间复杂度可控。窗口越小、桶越多统计越细腻但内存占用也越高。Sentinel 默认的统计配置在绝大多数场景下已经够用除非你做秒级甚至毫秒级的精细控制否则没必要去调整采样周期。对使用者来说理解滑动窗口的核心意义在于所有限流判断读到的 QPS 都是窗口周期内的平均值不是瞬时值。如果你发现限流阈值设 100但瞬时流量冲到 150 才被拦这不一定是 bug而是窗口算法的时间粒度决定的。4.4 自定义 Slot在合适的位置插入自己的逻辑框架设计者给 Slot 链留了扩展口你可以在默认链路里插入自己的 Slot。常见需求比如在流量进入统计之前记录来源 IP、对特定渠道做标记、在熔断前加入自定义告警。自定义 Slot 只需要继承AbstractLinkedProcessorSlot实现entry和exit两个方法然后通过扩展机制把新的 Slot 构建器注册进去。public class IpTraceSlot extends AbstractLinkedProcessorSlotDefaultNode { Override public void entry(Context context, ResourceWrapper resourceWrapper, DefaultNode node, int count, boolean prioritized, Object... args) throws Throwable { // 在流量判断前干一点自己的事 fireEntry(context, resourceWrapper, node, count, prioritized, args); } Override public void exit(Context context, ResourceWrapper resourceWrapper, int count, Object... args) { fireExit(context, resourceWrapper, count, args); } }插入位置非常关键。如果你的 Slot 想看到最终被限流的请求要放在 FlowSlot 之后如果想在规则判断前做一些统计准备要放在 StatisticSlot 之前。插错位置可能导致你拿到的数据半生不熟。大多数情况下你不需要自定义 Slot框架自带链路已经覆盖了主流场景先想清楚需求是不是真的“必须嵌进链路”可观测类需求通常更适合挂在日志或监控埋点上。5. Context那根把所有环节串起来的线5.1 Context 的生命周期与承载内容Context 是 Sentinel 体系里最容易被忽略、却最核心的一环。它本质上是一个请求维度的上下文对象通过线程局部变量维持包含入口节点、当前 Entry、调用来源、入口资源名等信息。每次业务请求进来时要在入口处手动或由适配层创建 ContextContextUtil.enter(web, consumerA); try (Entry entry SphU.entry(createOrder)) { // 业务逻辑 } finally { ContextUtil.exit(); }ContextUtil.enter的第一个参数是调用链入口名第二个参数是来源标识通常对应调用方应用名。请求结束时要调用ContextUtil.exit清理线程上的上下文否则这个线程下次处理其他请求时还带着上一请求的 Context 数据统计会串。Context 不是被传递来传递去的数据包它就在线程上下文里待着被当前线程里所有资源埋点共同引用。所以同一个请求里入口资源、下游子资源天然共享同一棵调用树。5.2 Entry 推动着调用树Node 的三层结构当代码进入一个资源时会生成一个 Entry 对象挂到 Context 上。同一个请求里可以同时存在多个资源 Entry先进后出形成树的深度。每个 Entry 背后对应着两个层面的统计节点DefaultNode 和 ClusterNode。DefaultNode是“上下文 资源”维度的节点同一请求链路里同一个资源对应一个 DefaultNode用于链路模式和来源统计。ClusterNode是“资源”维度的全局聚合节点无论哪个入口进来只要资源名相同都汇聚到同一个 ClusterNode用于单机资源维度的统计。Layer 关系大概是入口节点下挂 DefaultNode多个来源的 DefaultNode 共享同一个 ClusterNodeClusterNode 保存资源的整体统计。这也是为什么链路模式和单机阈值的行为表现不一样链路模式看的是某条具体调用链上的统计单机阈值看的是整个资源的聚合统计。Context 里的curEntry永远指向当前正在处理的 Entry。Entry 之间通过链表串联退出一个 Entry 时会把curEntry退回上一层。理解这层关系后你就能解释“为什么在链路模式下入口写错会导致规则失效”入口错调用树就挂错了父节点链路上的统计自然不在一条线上。5.3 子线程与异步调用中如何保住 Context这是全文最值得记住的坑之一。Sentinel 的 Context 默认放在 ThreadLocal 里ThreadLocal 的特性是线程隔离。当你把任务丢进线程池时子线程里拿不到父线程的 Context相当于调用树从根上断开了。断开的直接后果链路模式规则失效来源统计丢失更隐蔽的是子线程里创建的新 Context 会成为新的入口节点整棵树和父线程完全不连通。针对异步场景框架提供了专用的异步入口AsyncEntry entry SphU.asyncEntry(createOrder, EntryType.OUT); // 业务代码在异步回调里 if (entry ! null) { entry.exit(); }异步入口的原理是让上下文在异步链路上继续向后传递而不是依赖当前线程的 ThreadLocal。如果用普通SphU.entry包住异步任务只在父线程里创建 Entry回调线程退出时可能报 Context 为空或导致资源统计串到其他线程上。我自己实践下来的建议是异步调用链路统一走asyncEntry不要自己用 Runnable 包装器手工传递 Context。手工传递的方式对框架内部结构依赖太强版本一升级就会踩坑。如果你一定要在子线程里复用父线程 Context也要确保子线程执行期间父线程不会提前退出清理否则拿到的引用已经失效。6. 排障复盘规则不生效时按什么顺序查6.1 一张诊断表现象先对号入座平时群里问得最多的问题就是“我规则明明配了为什么没用”。这类问题多数集中在四个层面。我把常见现象、优先怀疑点和定位手段整理成了一张表排查时先对号入座现象优先怀疑点定位方法限流规则一次都没触发资源名对不上、规则没加载打印规则列表核对资源名限流时灵时不灵统计窗口粒度、阈值设置偏低对比监控 QPS 和规则阈值链路模式限流不生效Context 断了、入口名不一致打开链路统计观察入口节点异步调用场景规则全失效用了普通 entry 包异步逻辑改成 asyncEntry 重试被限流后没有降级数据BlockException 被吞了检查 LogSlot 输出和调用方 catch 逻辑系统保护疯狂误杀入口类型配错或系统指标阈值过低核对 EntryType 和系统保护参数第一反应不要直接调阈值。先确认“规则有没有到内存”“资源名是否一致”“Context 是否完整”这三件事排查完至少能排除一半问题。6.2 完整排查实例链路限流为何失效回到本文开头那个案例。服务 A 通过线程池并发调服务 B 的createOrder我们给“入口 A → 资源 B”配了链路限流目标是控制在 50 QPS。压测后 B 的吞吐突破了 5000规则完全没反应。排查第一步确认资源埋点没问题。B 侧的SphU.entry(createOrder)确实生效日志能看到每次调用都进入了 Slot 链。第二步确认规则加载正常。打印FlowRuleManager.getRules()规则存在阈值也是 50资源名和埋点名一字不差。第三步怀疑链路统计。打开链路维度的监控发现 B 侧资源的链路入口显示的不是“A”而是一个自动生成的线程名入口链路关系完全断裂。顺着调用链往回查发现 A 的出口调用是丢给线程池异步进行的。父线程的 Context 留在父线程子线程里 NodeSelectorSlot 找不到已有的入口节点干脆基于新线程建了一棵独立的树。父线程的调用树和子线程的调用树从此各走各的。第四步验证修复。把异步调用改为AsyncEntry方式让上下文在异步链路上延续规则立刻生效后续压测 QPS 精准卡在阈值附近。这个案例把四个概念串得严丝合缝资源埋点正确、规则加载正确但 Context 断了一环Slot 链里负责构建调用树的 NodeSelectorSlot 找不到父节点链路模式限流遵循的统计基础就不存在了。很多人遇到这种情况会怀疑是规则阈值问题其实问题远在链路起点。最后分享一个我自己养成的自检习惯。每次新接入一个资源先花十分钟过三关第一关资源名有没有重定义、动态参数、粒度失衡第二关入口和 Context 是否在同一个线程里完整创建、退出第三关规则用了哪种策略该策略依赖的是默认节点还是链路节点。三关都过了再遇到规则不生效你大概率可以直接判断出问题在框架配置之外而不是靠重启和调参来碰运气。