老实说，我最早对web-context-unify这个配置很不以为然。社区文档提了一句“是否整合Web上下文”，默认true，很多人根本不动它。直到有次帮一个项目组排查限流失效，现象很典型：链路流控规则在控制台配好了，规则显示已加载，压测就是不触发。我跟了一下午，最后发现所有HTTP请求在Sentinel里都被塞进了同一个上下文——sentinel_spring_web_context。在这个上下文下，调用链路的根节点只有一个，“链路”根本分不出第二条链，链路流控自然成了空架子。根因就是没关掉context整合。这篇文章就把这个配置彻底讲透：它在干什么、为什么要关、具体怎么关，以及关掉之后还会撞上的几个真实坑。
1. 链路流控的“入口”到底长什么样
1.1 三种流控模式的本质差异
先说清楚Sentinel的三种流控模式，很多人把链路模式当成“更高级的限流”，但没搞懂它在限什么维度。
直接模式最简单：对指定的某个资源单独做QPS或线程数限制。比如某个核心Service方法一秒最多处理50个请求，超了就抛BlockException。它完全不管请求从哪来，只要这个资源的调用量超过阈值，就挡。
关联模式稍微绕一点：它是让一个资源的流量去限制另一个资源。典型场景是数据库读写互斥——写操作太猛的时候，限制读操作的流量。规则里会有一个“关联资源”字段，当关联资源的QPS超过阈值时，目标资源开始限流。保护的是目标资源，触发条件却是另一个资源。
链路模式则完全不同。它不再把资源看作一个独立个体，而是把资源放在“调用链”里看：同样的资源，从入口A来的请求和从入口B来的请求，各算各的指标。用链路模式，你可以做到“入口A调这个方法的流量每秒限50，入口B调同一个方法每秒限100”。这个“入口”就是文章标题里提到的context整合要解决的问题。
| 模式 | 限制维度 | 典型场景 |
|---|---|---|
| 直接 | 单个资源本身 | 某个接口固定QPS阈值 |
| 关联 | 关联资源触发后限制目标资源 | 写库压力大时限制读接口 |
| 链路 | 指定入口到目标资源的链路段 | 不同入口调用同一核心方法分别限流 |
1.2 一个订单例子把链路模式说透
假设一个订单系统里，/order/create这个HTTP接口和/order/import这个批量导入接口，都会调用同一个核心方法OrderCoreService.create()。你希望人工下单入口走过来的每秒最多50次，批量导入入口走过来的最多100次，两者互不影响。
直接模式做不了这件事，因为它只认create()这个资源，50和100只能取一个数。链路模式就可以：配置两条规则，资源都是create()，入口分别指定为/order/create和/order/import。
关键问题是：Sentinel怎么知道某个请求进create()之前，是先从哪个入口进来的？这就是Context的职责。每个请求进入系统时，Sentinel会创建一个Context对象，给它赋予一个名字，这个Context名字就是“入口”。随后这个请求在代码里层层经过的每个资源节点，都会挂在以这个Context为根的调用树上。链路模式在统计时，就是在这棵树上找到“入口根”和“目标资源”之间的链路段，单独计数。
如果Context创建得不对，例如所有入口都叫同一个名字，那链路的维度就消失了。
2. context整合默认做了什么，不关掉为什么不行
2.1 默认情况下所有请求共用同一个上下文
在Spring Cloud Alibaba的Sentinel集成里，HTTP请求的拦截逻辑是由SentinelWebInterceptor完成的。这个拦截器在preHandle阶段创建一个Context，然后进入业务代码。创建Context的时候有个关键分支：
// SentinelWebInterceptor 核心逻辑（简化） if (contextUnify) { ContextUtil.enter(Constants.SENTINEL_SPRING_WEB_CONTEXT_NAME, ""); } else { ContextUtil.enter(requestUri, requestUri); }contextUnify由web-context-unify控制，默认是true。也就是说，默认情况下不管你请求的是/order/create还是/order/import，进入Sentinel的Context名字都统一叫sentinel_spring_web_context。于是调用树上所有请求的根节点都是同一个节点。
这就是问题所在。
你打开Sentinel Dashboard的“簇点链路”页面，如果看到所有资源都挂在同一个名为sentinel_spring_web_context的根节点下面，说明context整合还开着。此时你配置链路流控，入口资源实际上只有这一个根。无论请求从哪个URL进来，从链路模式的视角看，它们都是从同一个地方进来的。
2.2 链路树收不到正确入口的两种表现
这种情况下链路规则会有两种明显失效表现。
第一种：规则完全不触发。比如你配了一条链路规则，资源是OrderCoreService:create，入口是/order/create。但因为所有请求的Context名都是sentinel_spring_web_context，目标资源在调用树上的父节点根本不存在/order/create这个根，链路统计遍历树的时候找不到对应关系，规则形同虚设。
第二种：规则被“意外触发”或者误伤。如果入口资源配成了sentinel_spring_web_context，那所有从HTTP进来的请求都被算作同一条链路，链路模式退化成了直接模式，而且统计口径是聚合后的总量。更麻烦的是，如果代码里还有非HTTP入口（比如定时任务、MQ消费线程），那些请求会挂到默认的default上下文下，你是打算限HTTP入口还是连定时任务一起限？完全说不清。
所以，只要你想用链路模式做“按入口区分限流”，第一件事就是把web-context-unify关掉，让每个不同的URL Path都能成为独立的入口。
2.3 关闭后入口变多，资源开销也要算账
关掉context整合不是没有代价。true的时候，所有请求共享一个Context，内存里只需要维护一棵调用树；false之后，每个不同的URL都会成为一棵树的根节点。一个应用如果有几十个接口，就是几十棵树。
这个开销通常不大，Sentinel的Context和Entry不是每个请求都永久保留，核心节点是动态创建的。但如果你所有Controller接口都带UUID或者自增id这种高基数的动态参数，比如/order/10086/detail、/order/10087/detail，那么每来一个不同的id，就等于一个新的入口根节点。入口节点会越积越多，Dashhboard上的调用树会变得非常脆弱，内存占用和TreeMap维护成本都会明显上升。
所以关闭context整合之前，建议先看一眼自己的URL是不是高基数的动态路径。如果是，就要配合UrlCleaner做URL归一化，这块我会在最后一章单独讲。
3. 关闭context整合的实操配置
3.1 Spring Cloud Alibaba一行配置搞定
最常见的场景是项目用了spring-cloud-starter-alibaba-sentinel，这个配置项已经预留好了，不需要改代码。
spring: cloud: sentinel: web-context-unify: false这个配置作用在Web MVC适配的拦截器上。只改这一行，重启应用，HTTP请求的Context就会从统一的sentinel_spring_web_context变成独立的请求URI。
需要注意的是：配置项必须写在应用自己加载的配置里，而不是Dashboard上，它是客户端行为。改完之后如果发现不生效，先检查是不是引入了多个Sentinel相关starter，或者项目里默认注册的拦截器和适配器版本不一致。
3.2 原生Sentinel加Spring MVC的适配器配置
如果项目不是Spring Cloud Alibaba，而是直接引入sentinel-spring-webmvc-adapter，那就不能靠YAML配置了，要在代码里手动注册Sentinel的Web拦截器，并显式设置contextUnify(false)。
@Configuration public class SentinelWebConfig implements WebMvcConfigurer { @Override public void addInterceptors(InterceptorRegistry registry) { SentinelWebMvcConfig config = new SentinelWebMvcConfig(); config.setContextUnify(false); config.setHttpMethodSpecify(true); registry.addInterceptor(new SentinelWebInterceptor(config)).addPathPatterns("/**"); } }这里有个细节：setHttpMethodSpecify(true)会把HTTP方法也拼进资源名和入口名，比如GET:/order/create，而不是/order/create。如果你不确定适配器版本默认是什么行为，先打几笔流量，去Dashhboard看簇点链路里根节点的名字，再根据实际名字配置规则的refResource。
3.3 配置完怎么验证真的生效了
改完配置别急着写规则，先确认入口真的分开了。最直接的方法是去Dashhboard看“簇点链路”页面，正常情况下你会看到多个根节点，每个根节点对应一个URL入口。关闭前只有一个sentinel_spring_web_context，关闭后会出现/order/create、/order/import这类根节点。
也可以用临时接口打印一下当前线程的Context名称：
@GetMapping("/context-name") public String contextName() { Context context = ContextUtil.getContext(); if (context == null) { return "context is null"; } return context.getName(); }访问不同URL，如果返回的Context名各不相同，说明context整合已经关闭，链路已经能区分入口。
提示：这个接口调试完建议删掉，别留在生产环境。它本身也会被Sentinel拦截，相当于又多了入口节点。
4. 关掉之后我依然扑街：四个高频坑的完整排查
配置关掉了，入口也区分了，但链路流控还是不对。这部分的排查经验我觉得比配置本身更有价值。
4.1 坑一：@SentinelResource资源名根本没对上
链路规则里的resource字段，必须是调用树上真正存在的资源节点名。很多人配规则时写的是类名加方法名，比如OrderCoreService.create，但代码里的@SentinelResource写的是：
@SentinelResource("createOrder") public void create(OrderDTO order) { // ... }那规则里的resource就应该填createOrder，而不是OrderCoreService.create。
排查方法也很简单：去Dashhboard簇点链路，找到目标资源在树上的确切节点名，把这个名字原封不动抄到规则里。别自己脑补命名，命名错了规则必然不触发。
4.2 坑二：异步线程把上下文给丢了
Sentinel的Context默认绑定在线程的ThreadLocal上。如果你在Service方法里用了CompletableFuture.supplyAsync(() -> create())，或者把任务丢进了线程池，那么新线程执行create()时，ThreadLocal里是没有Context的。
没有Context的情况下，@SentinelResource切面会为当前线程创建默认的default上下文。结果就是：主线程的请求从/order/create进来，目标资源createOrder挂在/order/create树下；异步线程里又执行了一次create()，这次挂在default树下。链路规则只配了/order/create入口，异步那部分流量就完全逃掉了。
通道有两类处理方式。第一类是尽量把Sentinel统计放在同步链路里完成，异步分支单独做限流或干脆不开链路模式；第二类是新版本Sentinel提供的ContextUtil.runOnContext：
ContextUtil.runOnContext(targetContext, () -> { // 执行异步逻辑 });但要注意，targetContext需要你维护好，传入的Context不能随手关闭。用起来比较繁琐，建议项目里用异步场景时先确认这里确实成了限流盲区，再决定是否值得引入。
4.3 坑三：规则的refResource写错了对象
链路模式规则中，refResource填的是“入口资源名”，也就是Context名，而不是目标资源名。这两者非常容易混。
我见过一个真实配置：规则里resource填createOrder，refResource也填createOrder。这等于告诉Sentinel：看调用树里createOrder这个节点下面还有没有createOrder节点，当然找不到。规则要么不触发，要么报错。
正确写法是：
FlowRule rule = new FlowRule(); rule.setResource("createOrder"); rule.setGrade(RuleConstant.FLOW_GRADE_QPS); rule.setCount(50); rule.setStrategy(RuleConstant.STRATEGY_CHAIN); rule.setRefResource("/order/create"); rule.setLimitApp("default"); FlowRuleManager.loadRules(Collections.singletonList(rule));这里resource是被限流的资源，refResource是入口Context名。放张表对比一下：
| 字段 | 链路模式下填什么 | 含义 |
|---|---|---|
resource | createOrder | 被限流的目标资源节点 |
strategy | 2 | 表示链路模式 |
refResource | /order/create | 入口Context名，也就是树根 |
count | 50 | 每秒最大QPS |
4.4 坑四：想跨服务做链路，入口断在半路
链路模式统计的是单应用内一次请求的调用树。如果服务A的Controller调用了服务B的Feign接口，那么服务B收到的请求不会自动继承服务A的Context入口。Feign调用在链路维度上会把上下文断掉，因为Context本身没有跨网络传递的机制。
如果你真的想按“A服务哪个入口调用了B服务”来限流，常见做法是在A服务的Feign请求头里传入来源标识，B服务那边写一个Filter读取请求头，手动调用ContextUtil.enter(sourceName, origin)，再让B服务后续的@SentinelResource挂到它下面。
这样做复杂度不低，而且跨服务链路很容易因为超时、重试、异步把上下文搞乱。我的建议是：除非业务强需求要求跨服务链路限流，不然尽量只在单体应用内部用链路模式。跨服务限流优先考虑：按调用来源（origin）限流，配合RequestOriginParser解析请求头，用limitApp区分来源，比强行维护跨服务Context省心得多。
5. 链路模式规则的字段拆解与适用边界
5.1 FlowRule里的字段到底该填什么
通过代码加载规则时，FlowRule对象里关于链路模式的关键字段组合如下：
| 字段 | 取值 | 说明 |
|---|---|---|
resource | 资源名 | 要和@SentinelResource或SphU.entry里的名字一致 |
limitApp | default或来源名 | 默认不区分调用来源 |
grade | 0线程数 /1QPS | 阈值类型 |
count | 数值 | 阈值 |
strategy | 2 | 链路模式 |
refResource | 入口资源名 | 即ContextName |
如果用Dashboard界面配置，链路模式的入口资源会在下拉框里列出来，前提是当前机器已经上报过资源节点。这个顺序很重要：先跑几笔流量让资源出现在调用树上，再去配置链路规则。
5.2 limitApp和入口是两条不同的维度
很多人在看链路规则时会顺手填limitApp，把limitApp和refResource搞混。这两个字段虽然都能做“区分”，但维度完全不同。
refResource区分的是“从哪条调用链进来”，比如从/order/create入口还是/order/import入口；limitApp区分的是“调用来源是谁”，通常配合RequestOriginParser从请求头或参数里解析出来源应用名。来源和入口可以同时生效，但它们是两个独立的划分维度。
举个例子：来源App A和来源App B都会从/order/create入口调用createOrder。你只想限制App A的流量，可以配置limitApp=appA、refResource=/order/create。如果你不指定limitApp，那就是所有来源都按这个规则限。实际项目里这两个维度只要用好一个，大部分场景都够了，别同时叠太多维度，排障会很痛苦。
5.3 什么时候根本不该用链路模式
链路模式看起来强大，但用错场景就是给自己挖坑。我总结了几类不该用的场景：
- 只想对某个资源做全局总QPS限制。这种需求完全不需要链路，直接模式更简单，规则命中率也更高。
- 应用只有一个统一入口，比如所有请求都先经过同一个路由网关再转发。这种情况下链路模式约等于直接模式，多写一个入口参数纯属增加出错概率。此时更合适的方案是网关层的API分组限流。
- URL路径高度动态且没有做归一化。入口节点会不断增多，Dashboard调用树乱七八糟，维护成本极高。
- 调用链中存在大量线程池、异步、MQ消费。Context频繁丢失，链路模式统计出来的数字和真实请求对不上。
- 跨服务调用链。入口上下文不会自动传递，强上链路模式会让你被迫做一套自定义传递机制，性价比太低。
6. 动态URL入口归一化与我的三个检查习惯
6.1 动态路径不归一化，入口分分钟爆炸
关闭context整合后，URL里的动态参数会成为独立入口。如果接口是/order/detail/123和/order/detail/456，在Sentinel的调用树里就是两个根。流量复杂一点，根节点数量会迅速失控，Dashhboard卡顿不说，入口和规则也维护不过来。
解决方式是使用UrlCleaner，把动态路径规整成带占位符的模板：
@Bean public CommandLineRunner urlCleanerInitializer() { return args -> WebCallbackManager.setUrlCleaner((origin, path) -> path.replaceAll("/\\d+", "/{id}") ); }配置之后，/order/detail/123和/order/detail/456都会归一到/order/detail/{id}。链路规则里的refResource就写这个归一化后的模板入口。
这个操作应该在关闭context整合之前就先想好。不然后面入口爆炸了再补，清理存量节点和数据会比较麻烦。
6.2 我留下的三个检查习惯
把这次排障复盘完，我给自己定了三个固定检查步骤，现在写代码配Sentinel的时候基本都会先过一遍：
第一，配置任何链路规则之前，先看调用树。打开簇点链路，确认目标资源挂在哪个根节点下面，入口名到底是什么。看不清入口前不要动规则。
第二，改完web-context-unify之后，除了看Dashhboard，还要检查异步入口。项目里线池、MQ消费模块如果也在调用核心资源，要想清楚它们的Context从哪来，要不要单独设置入口。
第三，规则先从小阈值验证。把count调小到明显比实际流量低一截，压测一两分钟，确认限流真的按预期触发，再改回目标阈值。这样能快速验证配置链路是通的，而不是在规则不可见时盲目调参。
链路流控本身不复杂，复杂的是让Sentinel的调用树和真实业务入口对齐。很多问题看起来是规则写得不对，挖到底其实是context整合这个“默认配置”在作怪。把这层窗户纸捅破了，后面就顺多了。
