去年排查过一个挺有意思的限流故障：规则明明配好了，压测数据也上去了，但限流就是不生效。最后翻到代码层面，问题出在一个特别容易被忽略的细节上——资源埋点的位置在一个子线程里，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 管理，顺序通常不会错；但如果你在子资源里忘了exit，ThreadLocal 里的 Context 就一直挂着父资源，可能导致后续链路统计异常，甚至请求结束后内存里残留节点。
第三个是毫秒级统计场景下选了过粗的资源粒度。比如整个网关接口作为一个资源，底下包含多个后端调用，其中只有一个数据库查询是慢的。熔断规则配置在网关资源上，必然导致整个接口被熔断，大量本来健康的请求跟着遭殃。这类场景应该把资源粒度下沉到具体后端调用，或者把慢调用单独抽成资源，别让一颗老鼠屎坏了一锅汤。
3. 规则：从配置到生效的完整路径
3.1 规则家族成员与各自的核心参数
Sentinel 的规则不止大家最常用的限流。完整的规则家族我建议你用一张表记住：
| 规则类型 | 核心参数 | 作用 | 典型场景 |
|---|---|---|---|
| 流量控制规则 | resource、count、grade（QPS/线程数）、strategy（直连/关联/链路）、controlBehavior（直接拒绝/预热/匀速排队） | 限制单机或集群维度通过的流量 | 保护下游接口不被打垮 |
| 熔断降级规则 | resource、grade（RT/异常比例/异常数）、count、timeWindow | 当指标持续超阈值时熔断，窗口内快速失败 | 下游响应变慢、错误率飙升时兜底 |
| 系统保护规则 | highestCpuUsage、avgRt、maxThread、qps | 从系统维度做全局保护，防止整机雪崩 | 服务器负载过高时主动限流 |
| 授权规则 | resource、limitApp、白名单/黑名单 | 按调用来源做黑白名单控制 | 禁止某些来源调用核心接口 |
| 热点参数规则 | resource、paramIdx、paramFlowItemList | 对同一个资源里的特定参数值做差异化控制 | 某个热搜商品单独限流，不影响其他商品 |
流量控制规则里还有一个容易弄混的字段controlBehavior。默认是直接拒绝，适合大多数场景；预热模式适合刚启动的接口或有缓存预热的系统，让流量缓慢增长；匀速排队模式适合削峰填谷，系统会控制请求通过的间隔，而不是瞬间拒绝多余流量。
熔断降级规则里，不同的grade类型对应不同的计数方式。按 RT 熔断时，count是最大耗时；按异常比例熔断时，count是 0 到 1 的比例值；按异常数熔断时，count是异常次数。配置前先想清楚你要防的是“慢”还是“错”，两者对应的阈值语义完全不同。
3.2 规则从配置到检查的完整路径
规则配置好之后，它在内存里的组织方式和执行时的查找路径，很多人没有概念。拿流量控制规则举例：
List<FlowRule> 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、DefaultNode |
| ClusterBuilderSlot | 为资源创建或获取 ClusterNode，做跨 Context 聚合 | ResourceWrapper、ClusterNode |
| LogSlot | 记录异常日志 | BlockException 处理信息 |
| StatisticSlot | 统计维度数据，包括通过数、拒绝数、耗时等 | 滑动窗口 MetricBucket |
| ParamFlowSlot | 热点参数限流 | 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()); WindowWrap<MetricBucket> old = array.get(index); if (old == null || old.windowStart() + intervalInMs <= currentTimeMillis) { WindowWrap<MetricBucket> 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 AbstractLinkedProcessorSlot<DefaultNode> { @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、调用来源、入口资源名等信息。
每次业务请求进来时，要在入口处手动或由适配层创建 Context：
ContextUtil.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 共享同一个 ClusterNode，ClusterNode 保存资源的整体统计。这也是为什么链路模式和单机阈值的行为表现不一样：链路模式看的是某条具体调用链上的统计，单机阈值看的是整个资源的聚合统计。
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 是否在同一个线程里完整创建、退出；第三关，规则用了哪种策略，该策略依赖的是默认节点还是链路节点。三关都过了，再遇到规则不生效，你大概率可以直接判断出问题在框架配置之外，而不是靠重启和调参来碰运气。
