1. 从“context-mode”这个命名说起：它到底在解决什么问题
第一次看到context-mode这个词，很多人会下意识地把它当成某个框架里的配置项，或者某个库的开关参数。但如果你在代码库里真正翻过它的实现，会发现它更像是一种运行时的状态切换机制——它决定了当前这段逻辑到底以“谁”的身份、在“什么上下文”里执行。
我最早接触这个概念，是在处理一个多租户后台系统的时候。同一个接口，A 租户调用要看到 A 的数据，B 租户调用要看到 B 的数据，但底层查询逻辑完全一样。最笨的办法是每个方法都传一个tenantId参数，从 Controller 一路透传到 DAO 层。代码写起来是这样的：
public List<Order> listOrders(Long tenantId, Long userId) { return orderMapper.selectByTenantAndUser(tenantId, userId); }这种写法能跑，但问题很明显：参数像藤蔓一样缠满整条调用链，任何一个中间层忘了传，数据就串了。后来我们引入了一个ContextHolder，用 ThreadLocal 把当前请求的租户信息存起来，业务代码里直接ContextHolder.getTenantId()就能拿到。这时候context-mode的价值就体现出来了——它不是一个简单的工具类，而是一套上下文生命周期的管理策略。
context-mode的核心命题可以拆成三件事：
- 上下文的创建时机：是在请求入口创建，还是在真正需要的时候懒加载？
- 上下文的传播方式：是线程内共享，还是跨线程、跨异步任务传递？
- 上下文的清理策略：请求结束后立即销毁，还是等 GC 回收？
这三个问题看起来简单，但每一个选错，都会在生产环境里埋下难以排查的隐患。比如 ThreadLocal 忘记remove()，在 Tomcat 的线程池模型下，下一个请求复用同一个线程时就会读到上一个请求的脏数据。这种 bug 在测试环境几乎不可能复现，因为测试环境的并发量根本触发不了线程复用。
所以我在看context-mode相关实现时，第一眼关注的不是它提供了哪些 API，而是它在什么时机清理上下文。一个成熟的上下文管理方案，清理逻辑一定是和创建逻辑成对出现的，而且清理必须放在finally块里，不能依赖业务代码自觉调用。
提示：如果你正在设计自己的上下文管理模块，先把“清理”这件事想清楚，再动手写“创建”。清理比创建难十倍。
2. 上下文模式在真实项目里的四种典型落地形态
context-mode不是一个标准化的技术名词，它更像是一个设计模式的统称。在不同的技术栈和业务场景下，它的落地形态差异很大。我梳理了自己经手过的项目，把它归纳成四种最常见的形态，每种都有各自的适用边界和坑点。
2.1 请求级上下文：Web 应用里最常见的那种
这是最普遍的形态。一个 HTTP 请求进来，框架在入口处解析出用户身份、租户信息、链路追踪 ID，塞进一个上下文对象，然后整条调用链都从这个对象里取数据。Spring 的RequestContextHolder、Go 的context.Context、Node 的AsyncLocalStorage，本质上都在做这件事。
请求级上下文的关键设计点是存储介质的选择。Java 里常用 ThreadLocal，因为 Tomcat 一个请求由一个线程处理到底。但一旦你用了@Async或者线程池，ThreadLocal 就断了。这时候要么手动传递，要么用InheritableThreadLocal，但后者在线程池场景下同样会失效，因为线程是复用的，不会重新继承。
我踩过最典型的一个坑：在一个订单导出功能里，主线程把租户 ID 放进 ThreadLocal，然后提交了一个异步任务去查数据。异步任务跑在另一个线程里，ContextHolder.getTenantId()返回 null，结果查出来的是全量数据。这个 bug 在功能测试时完全没暴露，因为测试数据量小，导出的是全部租户的数据也没人发现。直到上线后某个租户导出了别人的订单，才被紧急叫停。
修复方案有两种：一是显式把上下文对象作为参数传给异步任务，二是用支持上下文传播的线程池包装器。前者侵入性强但直观，后者对业务代码透明但需要额外的基础设施。我后来倾向于后者，因为业务开发人员很容易忘记传参这件事。
2.2 会话级上下文：跨请求的状态保持
有些上下文不是单个请求内有效的，而是要跨多个请求保持，比如用户的登录态、购物车、多步表单的中间状态。这种场景下，上下文存储从 ThreadLocal 转移到了 Session 或者分布式缓存里。
会话级上下文最大的挑战是一致性和过期策略。用户可能在手机和电脑上同时操作，两个端的上下文如何同步？上下文过期时间设多长？用户操作到一半关掉浏览器，下次回来上下文还在不在？
我在一个多步审批流程里用过会话级上下文。每一步审批的状态都存在 Redis 里，key 是流程实例 ID。这里有个细节：Redis 的过期时间不能设得太短，否则用户填到一半去开个会回来，上下文没了，体验很差；但也不能太长，否则大量废弃的流程实例会占满内存。最后的方案是滑动过期——每次读写都刷新 TTL，同时设置一个绝对过期上限，比如 24 小时。这样活跃的流程不会中断，废弃的流程也能自动清理。
2.3 调用链上下文：分布式系统里的追踪与传递
微服务架构下，一个请求会经过网关、多个业务服务、数据库、消息队列。上下文需要在服务之间传递，这就是调用链上下文。它的核心载体是 Trace ID 和 Span ID，但实际项目里往往还会带上用户身份、租户信息、灰度标签等。
调用链上下文的传递依赖协议层的约定。HTTP 场景下通常放在 Header 里，比如X-Trace-Id、X-Tenant-Id。RPC 场景下放在附件（Attachment）里。消息队列场景下放在消息 Header 里。每经过一个中间件，都要确保上下文被正确透传，不能丢。
这里有个容易被忽略的点：跨进程传递的上下文必须是可序列化的。我见过一个项目把整个用户对象塞进 Header 里，结果 Header 超长被网关截断，导致下游服务解析失败。正确的做法是只传必要的标识符，比如用户 ID，下游服务需要详细信息时再回查。
2.4 测试级上下文：让单元测试不再互相污染
这个形态比较特殊，但在大型项目里非常实用。当你的测试用例依赖某个全局上下文时，用例之间的执行顺序会影响结果。比如用例 A 设置了当前用户是管理员，用例 B 期望当前用户是普通用户，如果 A 先执行且没有清理上下文，B 就会失败。
测试级上下文的核心是每个用例执行前后都要重置上下文。JUnit 里可以用@BeforeEach和@AfterEach，或者写一个自定义的 TestExecutionListener。我习惯在基类里统一处理，所有测试类继承这个基类，就不用每个用例都写一遍清理逻辑。
| 上下文形态 | 存储介质 | 生命周期 | 典型坑点 |
|---|---|---|---|
| 请求级 | ThreadLocal | 单次请求 | 异步任务丢失、线程池脏数据 |
| 会话级 | Session/Redis | 跨请求 | 过期策略、多端同步 |
| 调用链级 | Header/Attachment | 跨服务 | 序列化体积、透传遗漏 |
| 测试级 | 全局变量 | 单用例 | 用例间污染、清理遗漏 |
3. 自己动手实现一个可靠的 context-mode 需要盯住哪些细节
如果你打算在项目里自己实现一套上下文管理机制，而不是直接用现成的框架，下面这几个细节是我用血泪换来的经验，每一个都值得你花时间想清楚。
3.1 存储结构的选择：ThreadLocal 不是唯一答案
ThreadLocal 是最直觉的选择，但它有几个硬伤。第一，它和线程绑定，异步场景下会断。第二，它在线程池场景下需要手动清理，否则会内存泄漏。第三，它不支持父子线程的自动传递（InheritableThreadLocal只在线程创建时复制一次，线程池复用时不生效）。
替代方案有几种。Java 里可以用TransmittableThreadLocal（阿里开源的 TTL），它通过装饰线程池的 Task 来实现上下文传递。Go 里用context.Context显式传递，虽然啰嗦但最可靠。Node 里用AsyncLocalStorage，它基于异步资源追踪，能自动跟随异步调用链。
选择哪种，取决于你的技术栈和团队习惯。我的建议是：如果团队里异步代码多，优先选支持自动传播的方案，因为靠人自觉传递上下文，迟早会漏。
3.2 上下文的不可变性：防止中途被篡改
上下文对象一旦创建，里面的核心字段就不应该再被修改。我见过一个项目，在业务代码里直接ContextHolder.getContext().setTenantId(xxx)，结果在一个循环里不小心改错了租户 ID，导致后续所有操作都串了。
正确的做法是把上下文设计成不可变对象，需要修改时创建一个新的上下文替换旧的。这样虽然多了一点对象创建的开销，但换来了可预测性。如果性能确实敏感，可以用 Builder 模式或者写时复制（Copy-on-Write）来优化。
3.3 清理时机的把控：finally 块是底线
不管你的上下文存在哪里，清理逻辑必须放在finally块里。这是底线，没有例外。
public void doSomething() { Context ctx = ContextHolder.create(); try { // 业务逻辑 } finally { ContextHolder.clear(); } }如果你用的是框架提供的拦截器或过滤器，确认一下它的清理逻辑是否可靠。有些框架的清理是在afterCompletion里做的，但如果请求处理过程中抛出了未捕获的异常，afterCompletion可能不会执行。这种时候就需要在更外层兜底。
3.4 上下文的大小控制：别把它当成万能背包
上下文里放什么，不放什么，需要有明确的边界。我见过把整个 Request 对象、Response 对象、数据库连接都塞进上下文的，结果上下文对象巨大无比，每次传递都带来额外的开销。
我的原则是：上下文只放“标识性”信息，不放“内容性”信息。用户 ID、租户 ID、Trace ID 这些是标识，放进去没问题。用户详情、订单列表这些是内容，需要的时候去查，不要塞进上下文。
3.5 并发安全的保障：读写分离与快照
如果上下文可能被多个线程同时访问，就需要考虑并发安全。最简单的做法是用ConcurrentHashMap存上下文数据，但这样只能保证单个操作的原子性，复合操作仍然可能出问题。
更稳妥的做法是读写分离：写操作只在请求入口发生一次，之后所有线程都只读。如果确实需要中途修改，用快照机制——每个线程拿到的是上下文的副本，修改只影响自己的副本，不影响其他线程。
注意：上下文里的可变对象（比如 List、Map）即使容器本身是线程安全的，里面的元素也可能不是。如果多个线程会修改同一个 List，要么加锁，要么用不可变集合。
4. 排查上下文相关 bug 的完整思路链路
上下文相关的 bug 有个共同特点：难复现、难定位、难修复。因为它们往往和并发、时序、线程复用有关，在本地开发环境几乎不可能触发。我整理了一套排查这类问题的思路，按顺序走下来，大部分问题都能定位到根因。
4.1 第一步：确认上下文是否真的丢了
当业务表现异常时，先别急着怀疑上下文。有时候问题出在别的地方，只是恰好和上下文有关。比如数据查出来是错的，可能是 SQL 写错了，也可能是缓存脏了，不一定是上下文丢了。
确认的方法是在关键节点打印上下文快照。在请求入口打印一次，在业务逻辑执行前打印一次，在数据查询前打印一次。如果入口有值、查询前没值，那基本可以确定是上下文丢失。如果入口就没值，那是创建逻辑有问题。
打印的时候要注意，不要只打印toString()，因为很多上下文对象的toString()实现不完整。最好把关键字段逐个打印出来，比如tenantId=xxx, userId=xxx, traceId=xxx。
4.2 第二步：判断丢失发生在哪个环节
上下文丢失通常发生在几个特定的环节：线程切换、异步调用、远程调用、中间件穿越。根据你的代码结构，逐个排查。
线程切换是最常见的。如果你的代码里用了new Thread()、ExecutorService.submit()、CompletableFuture.supplyAsync()，上下文大概率会丢。检查这些地方有没有做上下文传递。
异步调用包括@Async注解、消息队列的发送和消费、定时任务。这些场景下上下文不会自动传递，需要手动处理。
远程调用包括 HTTP 调用、RPC 调用。检查 Header 或 Attachment 里有没有带上上下文信息。
中间件穿越包括网关、负载均衡、服务网格。这些组件可能会修改或丢弃 Header，需要确认它们的配置。
4.3 第三步：用最小复现单元验证猜想
一旦怀疑某个环节有问题，就写一个最小的测试用例来验证。比如怀疑线程池导致上下文丢失，就写一个简单的测试：主线程设置上下文，提交一个任务到线程池，任务里读取上下文，看是否能读到。
@Test public void testContextInThreadPool() { ContextHolder.set("tenant", "A"); ExecutorService executor = Executors.newFixedThreadPool(1); Future<String> future = executor.submit(() -> ContextHolder.get("tenant")); assertEquals("A", future.get()); }这个测试大概率会失败，因为线程池的线程和主线程不是同一个。失败之后，你就知道需要引入上下文传播机制了。
4.4 第四步：修复后的回归验证
修复之后，不能只跑一遍原来的测试就完事。要构造并发场景和异常场景来验证。
并发场景：用多个线程同时发起请求，每个请求设置不同的上下文，看是否会出现串数据。可以用 CountDownLatch 让所有线程同时开始，增加并发冲突的概率。
异常场景：在业务逻辑里故意抛异常，看上下文是否被正确清理。如果清理逻辑在finally里，异常不应该影响清理。如果清理逻辑在正常流程里，异常就会导致上下文残留。
4.5 第五步：加监控，防止问题再次发生
修复完一个上下文 bug 之后，最好加一个监控，在上下文丢失时打日志或报警。比如在关键业务逻辑执行前检查上下文是否为空，为空就记录一条警告日志，包含当前线程名、请求路径、Trace ID 等信息。
这样即使未来有新的代码路径导致上下文丢失，也能第一时间发现，而不是等用户投诉。
| 排查步骤 | 关键动作 | 常见发现 |
|---|---|---|
| 确认丢失 | 关键节点打印上下文 | 入口有值、查询前无值 |
| 定位环节 | 检查线程/异步/远程调用 | 线程池未传递、Header 未透传 |
| 最小复现 | 写针对性测试用例 | 线程池场景必失败 |
| 回归验证 | 并发+异常场景测试 | 清理逻辑不健壮 |
| 加监控 | 上下文为空时告警 | 发现新的丢失路径 |
5. 几个让我印象深刻的真实案例复盘
理论说再多，不如看几个真实案例。下面这三个案例都是我在实际项目中遇到的，每个都代表了context-mode使用中的一类典型问题。
5.1 案例一：线程池复用导致的租户数据串号
这是一个 SaaS 后台系统，多个租户共用一套服务。请求进来时，网关解析出租户 ID 放在 Header 里，服务端用一个拦截器把租户 ID 存进 ThreadLocal。业务代码里所有查询都从 ThreadLocal 取租户 ID，拼接到 SQL 的 WHERE 条件里。
上线初期一切正常。直到某天，一个租户反馈说看到了另一个租户的订单数据。我们紧急排查，发现是一个导出功能出了问题。导出功能用了线程池来并行查询多个分片的数据，但线程池里的线程没有继承主线程的 ThreadLocal，导致租户 ID 为 null，SQL 的 WHERE 条件里租户 ID 变成了IS NULL，查出了所有租户的数据。
修复方案是给线程池的 Task 包装一层，在 Task 执行前把主线程的上下文复制到子线程，执行后清理。这个包装器后来被抽象成了一个公共组件，所有用到线程池的地方都强制使用这个包装器。
这个案例的教训是：ThreadLocal 和线程池是天敌。只要你的项目里用了线程池，就必须考虑上下文传递问题。
5.2 案例二：异步日志导致 Trace ID 丢失
这是一个微服务项目，用 SkyWalking 做链路追踪。大部分请求的 Trace ID 都能正常串联，但有一部分请求的链路是断的，下游服务的 Trace ID 和上游对不上。
排查后发现，问题出在异步日志组件上。业务代码里用了一个自定义的异步日志工具，它内部维护了一个队列和一个消费者线程。日志事件被放入队列后，由消费者线程异步写入文件。但消费者线程没有继承请求线程的 Trace ID，导致日志里的 Trace ID 是空的。
更严重的是，这个异步日志工具还被用来记录一些业务审计信息，审计信息里的 Trace ID 为空，导致后续的审计分析无法关联到具体请求。
修复方案是修改异步日志工具，在日志事件里显式携带 Trace ID，消费者线程写入时从事件里取，而不是从 ThreadLocal 取。这个改动虽然小，但影响面很大，因为所有用到这个日志工具的地方都受益了。
5.3 案例三：测试用例之间的上下文污染
这是一个单元测试的问题。项目里有一个全局的上下文管理器，用来模拟登录用户。测试用例 A 把当前用户设置成管理员，测试用例 B 期望当前用户是普通用户。单独跑 B 的时候能通过，但 A 和 B 一起跑的时候 B 就失败。
原因是 A 执行完后没有清理上下文，B 执行时读到的还是 A 设置的管理员用户。这个问题在 CI 环境里特别明显，因为 CI 会跑全量测试，用例之间的相互影响会导致随机失败。
修复方案是在测试基类里加@AfterEach方法，每个用例执行完后重置上下文。同时约定，所有测试类必须继承这个基类。这个改动之后，测试的稳定性大幅提升，不再出现随机失败的情况。
6. 关于 context-mode 的一些个人实践建议
写了这么多，最后分享几条我在实际项目中总结出来的经验，都是踩过坑之后才明白的。
第一条：上下文管理要趁早做。项目初期代码少，上下文传递的问题不明显，很多人就懒得做。等到代码量上来，调用链变深，再想加上下文管理，改造成本会非常高。我的建议是，项目一开始就引入一个轻量的上下文管理模块，哪怕一开始只存一个 Trace ID，后面慢慢扩展。
第二条：不要过度依赖隐式传递。ThreadLocal 用起来很爽，业务代码里随处可取，但这恰恰是它危险的地方。隐式传递让调用关系变得不透明，你很难从方法签名看出它依赖哪些上下文。对于核心业务逻辑，我倾向于显式传参，虽然啰嗦，但可读性和可测试性更好。
第三条：上下文要有明确的归属。一个上下文对象应该只属于一个层次，比如请求级上下文就只放请求相关的信息，不要混入会话级或调用链级的信息。混在一起会导致生命周期管理混乱，清理时机难以确定。
第四条：写文档，写测试。上下文管理是基础设施，基础设施的稳定性直接影响所有业务。所以它必须有完善的文档和测试。文档要说明上下文的创建、传播、清理规则，测试要覆盖正常流程、异常流程、并发场景。
第五条：定期 review 上下文的使用。随着项目演进，上下文里可能会被塞进越来越多不该放的东西。定期 review 一下，把那些“内容性”的信息清理出去，保持上下文的轻量和纯粹。
这些建议看起来都是常识，但真正能做到的项目并不多。我自己也是在踩了足够多的坑之后，才慢慢把这些原则落实到项目里的。希望这些经验能帮你少走一些弯路。
