老实说我最早对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.runOnContextContextUtil.runOnContext(targetContext, () - { // 执行异步逻辑 });但要注意targetContext需要你维护好传入的Context不能随手关闭。用起来比较繁琐建议项目里用异步场景时先确认这里确实成了限流盲区再决定是否值得引入。4.3 坑三规则的refResource写错了对象链路模式规则中refResource填的是“入口资源名”也就是Context名而不是目标资源名。这两者非常容易混。我见过一个真实配置规则里resource填createOrderrefResource也填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名。放张表对比一下字段链路模式下填什么含义resourcecreateOrder被限流的目标资源节点strategy2表示链路模式refResource/order/create入口Context名也就是树根count50每秒最大QPS4.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里的名字一致limitAppdefault或来源名默认不区分调用来源grade0线程数 /1QPS阈值类型count数值阈值strategy2链路模式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的流量可以配置limitAppappA、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整合这个“默认配置”在作怪。把这层窗户纸捅破了后面就顺多了。