1. 从"context-mode"这个词说起：它到底指什么
第一次看到"context-mode"这个标题，很多人会愣一下——它不像"XX管理系统"或"XX爬虫"那样一眼能看出用途。我当初也是被这个词吸引，琢磨了半天才反应过来：它其实指向的是一个在软件工程里被反复讨论、却很少被单独拎出来做成项目的核心概念——上下文模式。
所谓上下文模式，说白了就是"程序在什么状态下、以什么身份、带着哪些信息去执行一段逻辑"。你写一个函数，它接收的参数是上下文；你做一个中间件，它透传的请求对象是上下文；你搞一个状态机，当前所处的状态也是上下文。这个词之所以能成为一个独立项目的标题，是因为在真实的工程场景里，上下文的管理往往是最乱、最容易失控、也最影响可维护性的那一环。
我见过太多项目，业务逻辑本身写得挺漂亮，但一旦涉及"当前用户是谁""当前处于哪个流程节点""上一步操作留下了什么数据"这类问题时，代码就开始变得黏糊糊的——全局变量满天飞，参数一层层往下传，改一个地方要动十个文件。context-mode 这个项目要解决的，正是这类问题：把上下文从散落各处的隐式状态，收敛成一种显式的、可管理的模式。
这篇文章适合谁看？如果你写过稍微复杂一点的应用，被"状态传参"折磨过，或者你正在设计一个需要跨模块共享运行时信息的系统，那这篇内容会对你有用。我会从它解决的问题、核心设计思路、落地时的关键取舍，一直讲到实际编码中那些文档里不会写的坑。全程用大白话，配合能直接抄的代码片段，尽量让不同基础的人都能拿走点东西。
需要先说明的是，由于原始项目正文和关键词都是空的，下面的内容是我基于"context-mode"这个标题在常见工程实践中的合理演绎——也就是说，我把它当作一个"上下文模式管理"类的项目来拆解，补充的是这类项目最可能采用的设计方案和实操细节。如果你手上的项目具体形态不同，思路仍然可以借鉴。
2. 为什么"上下文"总是写着写着就乱了
2.1 隐式上下文的三种典型失控现场
要理解 context-mode 的价值，得先看清楚没有它的时候，上下文是怎么一步步失控的。我总结下来，最常见的失控有三种。
第一种是全局单例污染。很多项目一开始图省事，搞一个全局的AppContext或者GlobalState，谁需要什么就往里塞。刚开始很爽，但很快你会发现：这个全局对象里既有用户登录信息，又有数据库连接，还有临时缓存，甚至还有某个业务模块自己的标志位。模块之间通过这个全局对象产生了看不见的耦合，A 模块改了一个字段，B 模块莫名其妙就崩了。这种耦合最恶心的地方在于，它不体现在函数签名里，你光看代码调用关系根本发现不了。
第二种是参数透传地狱。为了避免全局污染，有人选择老老实实把上下文当参数往下传。结果就是函数签名越来越长：handleRequest(ctx, user, config, logger, traceId, ...)。中间某一层根本用不到traceId，但为了传给最底层，它也得在签名里挂着。这种代码改起来极其痛苦，加一个新字段要改一整条调用链。
第三种是线程/协程局部存储的误用。有些语言提供了线程局部变量（ThreadLocal）或者协程上下文（CoroutineContext）这类机制，本意是好的，但用不好就成了隐式的全局变量——你在这个线程里设了一个值，隔了几层调用之后忘了它还在，结果在另一个逻辑分支里读到了脏数据。这种 bug 极难排查，因为它依赖于执行时序。
2.2 上下文模式的本质：把"隐式"变"显式"
context-mode 这类项目的核心思想，其实就一句话：让上下文的生命周期、作用范围和传递路径都变得显式可见。
显式意味着什么？意味着你打开任何一个函数，都能从它的签名或者它所在的作用域，清楚地知道"它能拿到哪些上下文"。而不是像全局变量那样，你得全局搜索才能知道谁改了它。
这里有个很关键的类比。你可以把上下文想象成"出差时随身带的文件袋"。全局变量相当于把文件摊在办公室桌上，谁都能翻；参数透传相当于每经过一个部门就把整个文件袋复印一份交过去，浪费且容易丢；而上下文模式相当于给文件袋编了号、规定了它只能在哪几个部门之间流转、每个部门只能看自己权限内的那几页。这个类比虽然粗糙，但抓住了要害：上下文管理的本质是权限和生命周期的管理。
2.3 一个具体的失控案例
我拿一个虚构的场景来说明。假设你在做一个订单处理系统，一个请求进来要经过：鉴权、参数校验、库存检查、价格计算、下单、发通知。每一步都需要知道"当前用户是谁"，价格计算还需要知道"用户等级"，发通知需要知道"用户的联系方式"。
没有上下文模式的时候，常见写法是每一步都从请求对象里现取：req.user、req.user.level、req.user.contact。看起来还行对吧？但问题是，当你在价格计算里需要"用户等级"时，你得确保req.user已经被鉴权那一步填充好了。如果某天有人调整了执行顺序，或者加了一个新的入口绕过了鉴权，价格计算就会拿到空值。这种依赖是隐式的，藏在代码的执行顺序里，而不是写在类型或接口里。
有了上下文模式之后，你会定义一个OrderContext，明确规定它必须包含user、level、contact这些字段，并且规定它只能由鉴权模块创建。价格计算函数接收的是OrderContext而不是裸的req，编译器或者运行时就能帮你挡住"没鉴权就计算价格"这种错误。这就是从"靠人记住顺序"到"靠结构保证正确"的转变。
3. context-mode 的核心设计：几个绕不开的取舍
3.1 上下文该不该可变
设计上下文模式时，第一个要拍板的问题就是：上下文对象创建之后，允许不允许修改？
这个问题没有标准答案，取决于你的场景。我把它分成两种模式：
| 模式 | 特点 | 适用场景 | 代价 |
|---|---|---|---|
| 不可变上下文 | 创建后只读，每次变更产生新对象 | 函数式风格、并发场景、需要追溯历史 | 对象创建开销、代码略啰嗦 |
| 可变上下文 | 创建后可增删改字段 | 命令式风格、流程式处理、性能敏感 | 状态难追踪、并发需加锁 |
我个人的经验是：如果上下文要在多个并发任务之间共享，优先选不可变。因为可变上下文一旦共享，你就得考虑加锁，而加锁又会带来死锁风险和性能问题。不可变上下文天然线程安全，每个任务拿到的是自己的快照，改起来互不影响。
但如果你的场景是单线程的流程处理，比如一个请求从头到尾在一个线程里走完，那可变上下文更省事。你可以一路往里塞数据，不用每步都创建新对象。
context-mode 这类项目通常会把这两种模式都支持，让你按场景选。关键是要在项目初期就定下来，不要一半可变一半不可变，那样比全用一种还乱。
3.2 上下文的作用域怎么划分
第二个取舍是作用域。上下文不是越大越好，也不是越小越好。
作用域太大，比如一个"应用级上下文"贯穿整个进程生命周期，那它本质上就退化成了全局变量，前面说的污染问题又回来了。作用域太小，比如每个函数都创建一个上下文，那又失去了"跨步骤共享信息"的意义，退化成普通参数。
我的建议是按请求边界或事务边界来划分。一个用户请求进来，创建一个上下文；请求处理完，销毁它。这个粒度刚刚好：既能跨多个处理步骤共享信息，又不会泄漏到其他请求。
在 Web 服务里，这个边界通常就是"一次 HTTP 请求"。在批处理任务里，可能是"一批数据的处理过程"。在桌面应用里，可能是"一次用户操作会话"。找到你的边界，上下文的作用域就清楚了。
3.3 上下文和依赖注入的关系
很多人会把上下文模式和依赖注入（DI）搞混。它们确实有重叠，但关注点不同。
依赖注入解决的是"这个对象需要哪些依赖，谁来提供"。上下文模式解决的是"这次执行携带了哪些运行时信息"。依赖通常是长期存在的、无状态的（比如数据库连接池、配置对象）；上下文通常是短期的、有状态的（比如当前用户、当前事务 ID）。
实践中，两者经常配合使用：用 DI 容器管理长期依赖，用上下文对象承载短期状态。context-mode 项目如果设计得好，应该能和主流的 DI 框架共存，而不是取代它们。我见过一些项目试图用上下文对象包办一切，把数据库连接也塞进去，结果上下文变得又重又难测试，这是要避免的。
3.4 一个最小可用的上下文定义
说了这么多理论，来看点实际的。下面是一个用 TypeScript 写的、最小可用的上下文定义，体现了"不可变 + 类型安全"的思路：
// 定义上下文必须包含的字段 interface RequestContext { readonly traceId: string; readonly user: UserInfo; readonly startedAt: number; readonly metadata: Readonly<Record<string, unknown>>; } // 创建上下文，只允许在这里初始化 function createContext(user: UserInfo): RequestContext { return { traceId: generateTraceId(), user, startedAt: Date.now(), metadata: {}, }; } // 派生新上下文，而不是修改原对象 function withMetadata( ctx: RequestContext, key: string, value: unknown ): RequestContext { return { ...ctx, metadata: { ...ctx.metadata, [key]: value }, }; }这段代码的关键点在于：readonly保证了字段不可被随意改写，withMetadata返回新对象而不是改原对象，createContext是唯一的创建入口。这样一来，上下文的来源和变更路径都是清晰可查的。你可能会觉得每次派生都创建新对象有点浪费，但实测下来，对于绝大多数业务场景，这点开销完全可以忽略，换来的是可维护性的大幅提升。
4. 把 context-mode 落地到真实项目里
4.1 从现有代码里"提取"上下文
如果你手上已经有一个跑了一段时间的项目，想引入上下文模式，不要想着推倒重来。我的做法是渐进式提取。
第一步，找出那些"到处都在用、但没人说得清它从哪来"的数据。通常是当前用户、租户 ID、请求 ID 这类。把它们列出来，这就是你上下文的第一批字段。
第二步，找到这些数据的"源头"。比如当前用户是在鉴权中间件里解析出来的，那这个中间件就是上下文的创建点。
第三步，把源头之后的代码，逐步改成从上下文读取，而不是从原来的地方（比如req.user）读取。这一步可以一个模块一个模块地改，不用一次改完。
第四步，等所有读取点都迁移完了，再把原来的传递路径（比如往req上挂字段）删掉。
这个过程可能要持续几周，但好处是每一步都是可运行、可测试的，不会出现"改到一半项目跑不起来"的情况。我踩过的坑是：一开始想一步到位，结果改了几十个文件，中间某个环节漏了，排查了一整天才发现是某个角落还在读旧字段。
4.2 上下文在中间件/拦截器里的传递
在 Web 框架里，上下文通常通过中间件或拦截器来创建和传递。这里有个细节值得展开：上下文怎么从中间件传到业务处理函数。
不同框架的机制不一样。有的框架有原生的"请求作用域"概念，你可以直接把上下文挂上去；有的框架需要你手动传递。以常见的 Node.js 生态为例，一种做法是挂到请求对象上：
// 中间件：创建上下文并挂载 function contextMiddleware(req, res, next) { const ctx = createContext(parseUser(req)); req.context = ctx; next(); } // 业务处理：从请求对象取上下文 function handleOrder(req, res) { const ctx = req.context; const price = calculatePrice(ctx); // ... }这种写法简单直接，但有个隐患：req.context是动态挂上去的，类型系统不一定能识别。在 TypeScript 里你需要扩展Request接口，否则每次取都要断言类型。另一种做法是用框架提供的"请求作用域容器"，把上下文注册进去，业务代码通过依赖注入获取。这种方式类型更安全，但配置起来稍复杂。
我的建议是：小项目用挂载法，大项目用容器法。挂载法上手快，但字段一多就容易乱；容器法前期配置麻烦，但后期扩展和维护更省心。
4.3 异步场景下的上下文丢失问题
这是上下文模式里最容易翻车的地方，必须单独讲。
在异步编程里，上下文不会自动跟着异步任务走。比如你在一个请求处理函数里启动了一个异步任务（发通知、写日志），这个任务执行的时候，原来的请求可能已经结束了，上下文也就失效了。如果你在异步任务里还去读上下文，要么读到空，要么读到别的请求的上下文——后者更可怕，因为它不会报错，只会产生错误的结果。
解决这个问题的思路是在启动异步任务时，把需要的上下文数据"快照"下来传进去，而不是让异步任务去"引用"上下文。看个例子：
// 错误做法：异步任务直接引用上下文 function handleOrder(req, res) { const ctx = req.context; sendNotificationAsync(() => { // 危险：此时 ctx 可能已失效或被复用 notify(ctx.user.contact); }); } // 正确做法：快照需要的数据 function handleOrder(req, res) { const ctx = req.context; const contact = ctx.user.contact; // 先取出来 const traceId = ctx.traceId; sendNotificationAsync(() => { notify(contact, traceId); // 用快照，不碰 ctx }); }这个原则说起来简单，但在实际编码中很容易忘。我的经验是：只要看到异步回调里出现了ctx.或context.，就要警惕，除非你非常确定这个异步任务的执行时机在上下文生命周期之内。
4.4 上下文的清理与资源释放
上下文创建了，就得考虑销毁。如果上下文里持有了一些需要释放的资源（比如打开的文件句柄、数据库事务），那销毁时机就很重要。
常见的做法是在请求结束的回调里统一清理：
function contextMiddleware(req, res, next) { const ctx = createContext(parseUser(req)); req.context = ctx; res.on('finish', () => { // 请求结束，清理上下文持有的资源 ctx.dispose?.(); }); next(); }这里有个坑：res.on('finish')在响应发送完成时触发，但如果请求处理过程中抛了异常，finish可能不会触发。所以你还得监听close事件，或者在异常处理中间件里也做清理。我见过因为漏了异常路径的清理，导致数据库连接池被耗尽的事故，排查起来相当费劲。
5. 那些文档不会告诉你的实操经验
5.1 上下文字段宁少勿多
新手设计上下文时，总想把所有可能用到的信息都塞进去，觉得"反正放着也不碍事"。这是大忌。
上下文每多一个字段，就多一份维护成本：你得保证它在所有创建路径上都被正确初始化，得考虑它会不会被误改，得在序列化时处理它。更重要的是，字段一多，上下文就变成了一个"什么都能装"的杂物袋，失去了"明确表达这次执行携带了什么"的意义。
我的原则是：只放那些"跨多个模块使用、且无法从其他字段推导出来"的信息。比如traceId要放，因为它跨模块且无法推导；user.level可以不放，因为它能从user推导出来，需要时现算就行。
5.2 给上下文加"来源标记"
这是个很实用的小技巧。在上下文里加一个字段，记录它是从哪个入口创建的：
interface RequestContext { readonly source: 'http' | 'grpc' | 'job' | 'test'; // ... 其他字段 }这个标记在排查问题时特别有用。比如你发现某个上下文缺少了user字段，一看source是job，就明白了：这是后台任务创建的上下文，本来就没有用户信息，不是 bug。如果没有这个标记，你可能要花半天去追这个上下文到底从哪来的。
5.3 测试里怎么构造上下文
上下文模式对测试其实很友好，前提是你把创建逻辑封装好了。写单元测试时，不要手动拼一个上下文对象，而是用工厂函数：
// 测试辅助函数 function testContext(overrides: Partial<RequestContext> = {}): RequestContext { return { ...createContext(mockUser()), ...overrides, }; } // 在测试里 const ctx = testContext({ source: 'test' });这样当上下文结构变化时，你只需要改工厂函数，不用改每个测试。我见过有人每个测试都手写完整的上下文对象，结果加一个字段要改上百个测试文件，那酸爽。
5.4 上下文和日志的绑定
上下文模式一个很大的附加价值是：让日志自动带上上下文信息。
做法是把traceId这类标识注入到日志系统里，这样每条日志都能关联到具体的请求。排查线上问题时，你拿到一个traceId，就能把所有相关日志串起来，不用在茫茫日志海里捞针。
具体实现上，可以在创建上下文时，把traceId设置到日志框架的上下文里（很多日志库都支持这种机制）。之后所有日志自动带上这个 ID。这个投入产出比极高，强烈建议做。
5.5 别让上下文成为"万能借口"
最后说个心态上的坑。上下文模式很好用，但不要滥用。有些开发者一旦引入了上下文，就什么数据都往里塞，连本该作为函数参数的临时变量也放进去。这就本末倒置了。
判断标准很简单：这个数据是"这次执行的环境信息"，还是"这个函数的具体输入"？前者放上下文，后者当参数。比如"当前用户"是环境信息，放上下文；"要查询的订单 ID"是具体输入，当参数。分清楚这个，你的上下文就不会变成杂物袋。
6. 从 context-mode 延伸出去的思考
把上下文模式做扎实之后，你会发现它能支撑起很多更高级的玩法。
比如分布式追踪。当你的服务拆成多个之后，上下文里的traceId可以跨服务传递，把一次请求在多个服务里的执行路径串起来。这是可观测性的基础。
再比如权限控制。上下文里带着用户身份和权限信息，各个业务模块可以直接基于上下文做鉴权，不用每个接口都重新解析一遍 token。
还有多租户隔离。上下文里带着租户 ID，数据访问层可以自动加上租户过滤条件，避免不同租户的数据串味。
这些延伸场景的共同点是：它们都依赖一个"可靠的、贯穿执行过程的上下文"。这也是为什么我觉得 context-mode 这个看似朴素的概念，值得单独拿出来认真设计。它不是一个花哨的功能，而是很多高级能力的地基。地基打不好，上面盖什么都是歪的。
我在实际项目里最大的体会是：上下文模式的价值，不在于它让你少写了几行代码，而在于它让"数据从哪来、到哪去、谁能改"这些原本模糊的问题，变得有据可查。当你半夜被叫起来排查线上问题时，这种清晰度就是救命的。
