1. 从“context-mode”这个命名说起它到底在解决什么问题第一次看到context-mode这个词很多人会下意识地把它当成某个库里的枚举值或者配置项。但如果你在代码里真的去搜会发现它并不是某个主流框架的标准 API。它更像是一个被开发者口口相传、逐渐固化成概念的说法用来描述一类非常具体的问题同一段逻辑在不同上下文环境下需要表现出不同的行为模式而你又不想为此维护多套代码分支。举个最直白的例子。你写了一个数据处理的函数在命令行里跑的时候你希望它把结果直接打印到终端在 Web 服务里被调用的时候你希望它返回 JSON在单元测试里跑的时候你希望它返回一个可以被断言的纯数据结构。这三个场景下核心计算逻辑完全一样变的只是“输出到哪儿”和“以什么形式输出”。如果你用if (isCLI) ... else if (isWeb) ... else if (isTest) ...来写代码很快就会变成一团乱麻。而context-mode这个思路就是把这层判断从业务逻辑里抽出来让上下文自己决定当前处于什么模式业务代码只负责“做事”不负责“判断自己在哪儿做事”。这个思路的价值在于它把环境感知和业务执行这两件事彻底解耦了。环境感知是基础设施层面的事业务执行是领域逻辑层面的事两者混在一起就是典型的架构腐化起点。我见过太多项目一开始只是加一个if (debug)后来变成if (debug !production platform ! web)最后没人敢动那段代码因为谁也不知道删掉一个条件会影响到哪个角落。所以当你看到context-mode这个标题时不要把它理解成某个具体的工具或库。它代表的是一种设计取向让上下文成为一等公民让模式切换变成显式声明而非隐式判断。接下来我会从实际落地的角度把这个思路拆开讲清楚包括它适合什么场景、不适合什么场景、怎么设计一套可维护的上下文模式体系以及我在真实项目里踩过的那些坑。2. 上下文模式的核心机制不是 if-else 的包装而是关注点分离2.1 上下文到底包含哪些维度很多人一提到“上下文”脑子里只有“运行环境”这一个维度。实际上在一个稍微正经点的系统里上下文至少包含以下几层信息维度典型取值影响范围运行环境开发、测试、预发、生产日志级别、错误处理策略、外部依赖地址调用来源CLI、HTTP、消息队列、定时任务输入解析方式、输出格式、超时策略用户身份匿名、普通用户、管理员、系统内部权限校验、数据过滤、审计粒度执行阶段初始化、运行中、关闭中资源分配、优雅退出、状态持久化数据敏感度公开、内部、机密脱敏规则、加密要求、传输通道context-mode要做的就是把这些维度统一抽象成一个上下文对象然后在关键决策点根据这个对象的当前状态来选择行为模式。注意这里说的是“选择行为模式”而不是“执行具体逻辑”。行为模式是策略层面的东西具体逻辑是执行层面的东西两者必须分开。我见过一个反例有人在业务函数里直接读环境变量然后根据NODE_ENV的值决定要不要发告警邮件。结果测试环境跑集成测试的时候因为NODE_ENV没设对给全组人发了一百多封告警邮件。这就是典型的上下文判断散落在业务代码里导致的灾难。正确的做法是上下文对象在应用启动时就被确定下来业务代码只问“当前模式是什么”而不问“当前环境变量是什么”。2.2 模式切换的三种实现路径实现context-mode的思路大致有三种各有各的适用场景我逐一分析。第一种策略注册表。你定义一个模式到处理器的映射表比如{ cli: CliHandler, web: WebHandler, test: TestHandler }然后在入口处根据上下文选择对应的处理器。这种方式的优点是扩展性好新增一个模式只需要注册一个新的处理器不需要改任何现有代码。缺点是如果模式之间共享大量逻辑你需要在处理器之间做组合或者继承容易产生层次过深的问题。第二种中间件管道。把上下文相关的处理逻辑做成一系列中间件每个中间件负责一个维度的判断和转换。比如第一个中间件处理输入解析第二个中间件处理权限校验第三个中间件处理输出格式化。这种方式的优点是逻辑清晰每个中间件只关心一件事。缺点是调试起来比较麻烦因为一个请求经过多个中间件之后你很难一眼看出最终的行为是由哪个中间件决定的。第三种上下文注入。在函数调用链的起点创建一个上下文对象然后通过参数传递或者依赖注入的方式把这个对象传到每一个需要它的地方。业务函数根据上下文对象里的模式字段来决定行为。这种方式的优点是显式、可追踪你打开任何一个函数都能从签名里看出它依赖什么上下文。缺点是需要传递的对象可能很大而且如果调用链很深参数传递会很繁琐。我在实际项目里最常用的是第一种和第三种的混合在应用入口用策略注册表确定顶层模式然后把上下文对象注入到业务层业务层内部再用小的策略表来处理局部模式切换。这样既保证了顶层结构的清晰又避免了深层调用链的参数传递问题。2.3 为什么不能直接用依赖注入框架替代有人可能会问我用依赖注入框架把不同环境下的实现类注入进去不就行了吗为什么还要单独搞一套context-mode这个问题问得好。依赖注入解决的是实现替换的问题而context-mode解决的是行为选择的问题。这两者有重叠但不完全一样。举个例子。你的系统需要发送通知。在开发环境下你希望通知只打印到控制台在测试环境下你希望通知写入一个内存队列供断言在生产环境下你希望通知真正发出去。用依赖注入你可以定义Notifier接口然后提供ConsoleNotifier、MemoryNotifier、RealNotifier三个实现在启动时根据环境注入不同的实现。这没问题。但是如果同一个进程里需要同时支持多种模式呢比如一个服务既接受 HTTP 请求又消费消息队列还提供 CLI 管理命令。HTTP 请求的通知要发到用户邮箱消息队列的通知要写入审计日志CLI 命令的通知要打印到终端。这时候依赖注入就不够用了因为注入是在启动时确定的而模式是在运行时根据调用来源动态变化的。context-mode的核心价值就在这里它支持运行时动态模式切换而依赖注入通常只支持启动时静态实现替换。当然两者可以结合使用。顶层用依赖注入确定基础设施运行时用context-mode处理动态行为选择。这是我在复杂系统里最推荐的组合方式。3. 落地一套 context-mode 体系从目录结构到代码组织3.1 目录结构设计一套可维护的context-mode体系目录结构应该让“模式”这个概念在文件系统层面就可见。我通常采用这样的组织方式src/ contexts/ index.ts # 上下文对象的定义和创建逻辑 detector.ts # 从运行环境中检测当前上下文的逻辑 modes/ cli.ts # CLI 模式下的行为定义 web.ts # Web 模式下的行为定义 test.ts # 测试模式下的行为定义 core/ services/ # 业务逻辑不直接依赖具体模式 handlers/ # 模式相关的处理器按模式分目录 entry/ cli.ts # CLI 入口创建 CLI 上下文 server.ts # HTTP 入口创建 Web 上下文这个结构的关键在于contexts/modes/目录。每个模式一个文件文件里定义该模式下所有需要变化的行为。当你要新增一个模式时只需要在这个目录下加一个文件然后在detector.ts里注册检测逻辑。业务代码完全不用动。我见过很多项目把模式相关的代码散落在各个业务模块里比如userService.cli.ts、userService.web.ts这种命名方式。这种方式在模式数量少的时候还能忍一旦模式超过三个文件数量就会爆炸而且你很难一眼看出某个模式到底影响了哪些业务模块。集中式的modes/目录解决了这个问题。3.2 上下文对象的字段设计上下文对象不要设计得太胖。我见过有人把整个process.env塞进上下文对象结果这个对象序列化之后有几十 KB日志里打出来根本没法看。上下文对象应该只包含影响行为决策的最小信息集。我的经验是上下文对象包含以下几类字段就够了mode: 当前主模式比如cli | web | test这是最重要的字段。flags: 一组布尔标志比如isDebug、isDryRun、isVerbose用来控制细节行为。metadata: 一些元信息比如requestId、userId、startTime用于日志和追踪。capabilities: 当前上下文具备的能力比如canWriteFile、canSendNetwork、canPromptUser业务代码根据这些能力来决定是否执行某些操作。capabilities这个设计是我踩坑之后加上的。早期我直接用mode来判断业务代码里到处是if (ctx.mode cli)。后来发现有些能力在多个模式下是共享的比如 CLI 和 Web 都能写文件但测试模式不能。如果只用mode判断就会写出if (ctx.mode cli || ctx.mode web)这种重复逻辑。改成if (ctx.capabilities.canWriteFile)之后逻辑清晰多了而且新增模式时只需要声明它具备哪些能力不需要改业务代码。3.3 模式检测的时机与策略模式检测应该在应用启动的最早阶段完成而且只做一次。不要在每次函数调用时都去检测当前模式那样性能开销不说逻辑上也会变得混乱——万一检测逻辑本身依赖某个还没初始化的东西呢检测策略通常是按优先级依次尝试如果存在显式的命令行参数比如--modecli直接用这个。否则检查环境变量比如APP_MODE。否则根据运行时的特征推断比如process.stdin.isTTY为真说明是交互式终端process.env.NODE_ENV test说明是测试环境。如果都检测不到使用一个安全的默认模式通常是cli或者unknown。这里有个坑要注意不要根据NODE_ENV来推断模式。NODE_ENV是给构建工具和第三方库看的它只有development、production、test三个约定值不足以表达你的业务模式。我见过有人用NODE_ENVproduction来判断是否应该发送真实通知结果在预发环境也是production里把测试通知发给了真实用户。正确的做法是定义一个独立的APP_MODE变量和NODE_ENV解耦。3.4 业务代码如何消费上下文业务代码消费上下文的方式决定了这套体系最终是清晰还是混乱。我的原则是业务函数只读上下文不写上下文只根据上下文做分支不根据上下文做副作用。什么意思举个例子。一个发送通知的函数它应该这样写function sendNotification(ctx: Context, userId: string, message: string) { if (!ctx.capabilities.canSendNetwork) { ctx.logger.info([dry-run] would send to ${userId}: ${message}); return; } // 真正发送通知的逻辑 return notificationService.send(userId, message); }注意这个函数没有去判断ctx.mode test而是判断ctx.capabilities.canSendNetwork。这样无论未来新增什么模式只要该模式声明了canSendNetwork: false这个函数就会自动进入 dry-run 分支不需要改一行代码。另一个原则是上下文对象应该是不可变的。一旦创建就不应该在运行过程中被修改。如果某个中间件需要改变行为它应该创建一个新的上下文对象而不是修改原有的。这样可以避免“上下文在调用链中被意外篡改”这类难以排查的问题。我在一个项目里遇到过某个中间件为了临时关闭日志直接把ctx.flags.isVerbose false结果这个修改影响了后续所有请求因为上下文对象是单例的。改成不可变之后每个请求都有自己的上下文副本问题就消失了。4. 真实场景拆解三种典型模式下的行为差异4.1 CLI 模式交互性与退出码CLI 模式最特殊的地方在于它和用户的交互是同步的、有状态的。用户输入一个命令程序执行输出结果然后退出。这个过程中程序需要处理用户的输入提示、进度显示、错误信息格式化以及最重要的——退出码。在context-mode体系里CLI 模式通常声明以下能力canPromptUser: true、canWriteFile: true、canSendNetwork: true、isInteractive: true。业务代码根据isInteractive来决定是否显示进度条根据canPromptUser来决定是否弹出确认对话框。退出码是 CLI 模式独有的关注点。在 Web 模式里错误通过 HTTP 状态码表达在 CLI 模式里错误通过退出码表达。我通常会在上下文对象里加一个exitCode字段业务代码在遇到错误时设置这个字段然后在入口处统一根据它来调用process.exit()。这样业务代码不需要直接调用process.exit()测试的时候也更容易断言。// entry/cli.ts const ctx createContext({ mode: cli }); try { await runCommand(ctx, process.argv.slice(2)); } catch (err) { ctx.logger.error(err.message); ctx.exitCode 1; } process.exit(ctx.exitCode);这里有个细节process.exit()会立即终止进程不会等待未完成的异步操作。如果你的程序里有正在写入的文件流或者正在发送的网络请求直接退出会导致数据丢失。正确的做法是设置process.exitCode而不是调用process.exit()让 Node.js 在事件循环清空后自然退出。只有在确实需要强制退出时才调用process.exit()。4.2 Web 模式请求隔离与并发安全Web 模式和 CLI 模式最大的区别在于并发。CLI 模式一次只处理一个命令上下文是全局唯一的Web 模式同时处理多个请求每个请求都有自己的上下文。这意味着上下文对象不能是单例必须每个请求创建一个。在context-mode体系里Web 模式的上下文通常在中间件里创建然后挂载到请求对象上。后续的处理器从请求对象里取上下文而不是从全局变量里取。这是保证并发安全的关键。// middleware/context.ts export function contextMiddleware(req, res, next) { req.ctx createContext({ mode: web, metadata: { requestId: generateRequestId(), userId: req.user?.id, startTime: Date.now(), }, capabilities: { canPromptUser: false, canWriteFile: false, canSendNetwork: true, isInteractive: false, }, }); next(); }注意canPromptUser: false和isInteractive: false。Web 请求不能弹出交互式对话框也不能假设有终端可以显示进度条。如果业务代码里有一个函数在 CLI 模式下会提示用户确认在 Web 模式下它应该直接抛出错误或者返回一个需要确认的响应而不是阻塞等待。这就是capabilities字段的价值它让业务代码能够以统一的方式处理不同模式下的能力差异。另一个 Web 模式特有的问题是超时。CLI 命令可以跑几分钟甚至几小时但 HTTP 请求通常有超时限制。上下文对象里应该包含一个deadline字段业务代码在执行耗时操作前检查这个字段如果剩余时间不足就提前终止。这比在网关层硬性切断连接要优雅得多因为业务代码有机会做清理工作。4.3 测试模式确定性与可断言性测试模式的核心诉求是确定性。同样的输入必须产生同样的输出不能依赖当前时间、随机数、网络状态或者文件系统。context-mode在测试模式下的作用就是把这些不确定性来源全部替换成可控的桩。测试模式的上下文通常声明canSendNetwork: false、canWriteFile: false、canPromptUser: false并且提供一个clock字段用于获取当前时间一个random字段用于生成随机数。业务代码不直接调用Date.now()或Math.random()而是通过上下文对象获取。这样在测试时你可以注入一个固定时间的时钟和一个固定序列的随机数生成器让测试结果完全可预测。// core/services/order.ts function createOrder(ctx: Context, items: Item[]) { const orderId ctx.random.uuid(); const createdAt ctx.clock.now(); // ... }这个模式一开始会让人觉得繁琐但一旦习惯之后你会发现测试变得极其稳定。我再也没有遇到过“这个测试昨天还能过今天怎么就挂了”的情况因为所有不确定性来源都被上下文接管了。测试模式还有一个容易被忽略的点清理逻辑。测试结束后上下文应该负责清理它创建的所有资源比如临时文件、内存队列、数据库连接。我通常会在上下文对象上挂一个cleanup函数数组业务代码在创建资源时把清理函数注册进去测试框架在afterEach里统一调用。这样就不会出现测试之间互相污染的问题。5. 踩坑实录那些让我重构三次的上下文陷阱5.1 上下文泄漏当全局状态伪装成上下文我做过一个项目一开始为了图方便把上下文对象挂在了全局变量上。CLI 模式下没问题因为一次只跑一个命令。后来加了 Web 模式问题就来了两个并发请求请求 A 把上下文设成mode: web请求 B 也设成mode: web看起来没问题。但请求 A 在处理过程中临时把ctx.flags.isDryRun true结果请求 B 读到了这个标志行为变得莫名其妙。这个问题的根源在于我把“上下文”当成了“全局配置”。上下文应该是请求级别的每个请求一份互不干扰。全局配置是另一回事它应该是只读的在启动时确定运行时不修改。两者混在一起就是灾难。修复方案很简单上下文对象通过参数传递或者请求对象挂载绝对不放在全局变量里。全局配置单独放在一个config对象里标记为readonly任何试图修改它的代码都会在编译时报错。5.2 模式判断散落从一处判断到处处判断第二个坑是模式判断的扩散。一开始我只在入口处判断一次模式然后根据模式选择不同的处理器。后来需求变了某个业务函数在 CLI 模式下需要多打印一些调试信息在 Web 模式下不需要。于是我在那个函数里加了一个if (ctx.mode cli)。再后来另一个函数也需要类似判断我又加了一个。半年后代码里到处都是ctx.mode cli新增一个模式时我不得不全局搜索替换。这个问题的根源在于我把“模式”当成了行为判断的唯一依据。正确的做法是把模式转换成能力业务代码判断能力而不是判断模式。比如“是否需要多打印调试信息”这件事应该抽象成ctx.capabilities.isVerboseCLI 模式下这个能力为trueWeb 模式下为false。这样业务代码里只有if (ctx.capabilities.isVerbose)新增模式时只需要声明该模式是否具备这个能力不需要改业务代码。这个重构花了我整整两天时间但之后新增模式的时间从半天缩短到了十分钟。这笔账怎么算都划算。5.3 异步上下文丢失await 之后的上下文去哪了第三个坑最隐蔽。在 Node.js 里如果你用AsyncLocalStorage来存储上下文大部分情况下没问题。但如果你在某个地方用了setTimeout、setImmediate或者事件监听器上下文可能会丢失。因为AsyncLocalStorage是基于异步调用链的一旦调用链断裂上下文就取不到了。我遇到的具体场景是一个 Web 请求在处理过程中把一个任务丢到了setTimeout里异步执行。等setTimeout的回调触发时AsyncLocalStorage.getStore()返回undefined因为此时已经不在原来的异步调用链里了。结果那个任务里的所有日志都丢失了requestId排查问题时完全串不起来。解决方案是在把任务丢到setTimeout之前先手动捕获当前上下文然后在回调里恢复const ctx getContext(); setTimeout(() { runWithContext(ctx, () { // 这里的代码可以正常获取上下文 }); }, 1000);这个坑让我意识到上下文传递不是自动的尤其是在跨越异步边界的时候。每次把任务交给外部调度器定时器、事件发射器、消息队列都要显式地传递上下文。后来我干脆封装了一个scheduleWithContext工具函数所有异步调度都走这个函数避免遗漏。5.4 上下文对象的序列化陷阱第四个坑和日志有关。我习惯把上下文对象直接打进日志方便排查问题。但上下文对象里可能包含循环引用比如ctx.parent ctx或者包含不可序列化的东西比如函数、流对象。直接JSON.stringify(ctx)会抛错或者产生巨大的日志。解决方案是给上下文对象实现一个toJSON()方法只返回需要记录的字段。或者更简单一点在日志中间件里手动挑选字段logger.info({ mode: ctx.mode, requestId: ctx.metadata.requestId, userId: ctx.metadata.userId, flags: ctx.flags, }, request started);不要偷懒把整个上下文对象丢进日志。日志是给人看的不是给机器解析的精简比完整更重要。6. 进阶让 context-mode 体系具备自我演进能力6.1 模式的能力声明与校验当模式数量增加到五六个的时候手动维护每个模式的能力声明就容易出错。比如你新增了一个模式忘了声明canWriteFile业务代码读取这个字段时得到undefined在布尔判断里等同于false行为可能不符合预期。我的做法是定义一个能力清单每个模式必须显式声明所有能力缺一个就在启动时报错const REQUIRED_CAPABILITIES [ canPromptUser, canWriteFile, canSendNetwork, isInteractive, isVerbose, ] as const; function validateCapabilities(mode: string, caps: Recordstring, boolean) { for (const cap of REQUIRED_CAPABILITIES) { if (typeof caps[cap] ! boolean) { throw new Error(Mode ${mode} is missing capability ${cap}); } } }这个校验在应用启动时执行任何模式声明不完整都会立即暴露而不是等到运行时才出现诡异行为。这个做法是我从一个同事那里学来的他管这叫“让错误尽早发生”。我觉得这是上下文模式体系里最重要的一条工程原则。6.2 模式之间的继承与组合有些模式之间共享大量行为。比如web和webhook都是 Web 相关的都具备canSendNetwork: true和isInteractive: false区别只在于webhook不需要用户认证。如果每个模式都从头声明所有能力会有大量重复。我的做法是允许模式之间继承const webCapabilities { canPromptUser: false, canWriteFile: false, canSendNetwork: true, isInteractive: false, isVerbose: false, }; const modes { web: webCapabilities, webhook: { ...webCapabilities, requiresAuth: false }, cli: { ...webCapabilities, canPromptUser: true, canWriteFile: true, isInteractive: true }, };这样公共能力定义一次差异部分显式覆盖。新增模式时先找一个最接近的现有模式继承然后只声明差异。这比从头写一遍要快得多也不容易遗漏。6.3 上下文模式的文档化最后一个进阶话题是文档化。上下文模式体系最大的风险是“只有写的人知道”。新人进来看到ctx.capabilities.canWriteFile不知道这个能力在哪些模式下为true也不知道为什么某个模式不能写文件。如果没有文档他们只能去读源码而源码可能散落在多个文件里。我的做法是在contexts/modes/目录下放一个README.md用表格列出所有模式及其能力声明并解释每个能力为true或false的原因。这个文档不需要很正式但必须和代码同步更新。我通常在代码审查时检查如果某个 PR 修改了模式的能力声明但没有更新这个文档就打回去。模式canPromptUsercanWriteFilecanSendNetworkisInteractive说明clitruetruetruetrue交互式命令行用户在场webfalsefalsetruefalseHTTP 请求无用户交互webhookfalsefalsetruefalse外部回调无用户交互无认证testfalsefalsefalsefalse单元测试所有副作用被禁用batchfalsetruetruefalse批处理任务可写文件但无交互这张表放在文档最前面任何人想了解某个模式的行为看一眼就够了。这比读代码快十倍。7. 我个人的经验总结什么时候该用什么时候不该用context-mode这套思路不是银弹。我在一些项目里用了效果很好在另一些项目里用了反而增加了复杂度。区别在哪里适合用的场景同一个核心逻辑需要在多种环境下运行且环境差异主要体现在输入输出和副作用上。比如一个数据处理管道既要在 CLI 里跑又要在 Web 服务里跑还要在测试里跑。这种情况下把环境差异抽象成上下文模式收益非常明显。不适合用的场景环境差异很小或者差异主要体现在配置上而不是行为上。比如一个纯计算函数无论在什么环境下都是同样的输入输出那就没必要引入上下文模式。直接写一个纯函数让调用方处理环境差异就行了。还有一个判断标准如果你发现上下文对象里的字段超过十个或者模式数量超过五个就要警惕了。这通常意味着你的系统边界不够清晰或者你在试图用上下文模式解决一个应该用架构分层解决的问题。上下文模式是战术层面的工具不是战略层面的架构。它解决的是“同一段逻辑在不同环境下行为不同”的问题不解决“系统太复杂需要拆分”的问题。最后分享一个我在实际使用中总结的小技巧给上下文对象加一个describe()方法返回一个人类可读的字符串比如cli (interactive, verbose, can-write)。在日志里、在错误信息里、在调试输出里用这个字符串代替完整的上下文对象。这样既保留了关键信息又不会让日志变得臃肿。这个技巧看起来很小但在排查问题时能省下大量时间。