context-mode：集中管理环境判断的代码设计模式

前几天在改一套老代码，又被满屏的if (isProd) ... else if (isStaging) ...搞得心烦意乱。这些年经手的项目越多，越发现一个规律：真正让系统变乱的往往不是业务逻辑本身，而是散落各处的环境判断、角色判断、请求来源判断。于是我把之前提炼过的一套思路重新整理了一下，起了个名字叫 context-mode，也就是“上下文模式”。它的核心就一句话：把“当前处于什么场景”这件事集中管理起来，让业务代码只说需求，不判断环境。这篇文章就围绕 context-mode 讲清楚它的设计思路、核心机制和一套可以直接抄走的实现，适合正在做中后台系统、工具链、多环境部署脚本，或者对代码可维护性有执念的工程师参考。

1. 为什么要做 context-mode：被环境判断逼疯的日常

1.1 老项目中那些脏乱差的环境判断

我见过太多项目的环境判断逻辑长成下面这个样子：

const isProd = process.env.NODE_ENV === 'production'; const isStaging = process.env.IS_STAGING === 'true'; const isLocal = !isProd && !isStaging; const useMock = process.env.USE_MOCK === '1'; if (isProd) { logger.level = 'warn'; } else if (isStaging) { logger.level = 'debug'; } else { logger.level = 'silly'; } if (useMock && !isProd) { // 走 mock 数据 } else { // 走真实接口 }

单看这段代码好像还行，但真实项目里这种判断会散布在十几个文件里。有人用NODE_ENV，有人用APP_ENV，还有人自己发明一个DEPLOY_ENV。最离谱的一次，我看到某个模块判断测试环境的变量是IS_TEST，另一个模块用的是STAGING_FLAG，两个变量同时存在但含义重叠，改配置的人根本分不清该改哪个。环境判断一旦乱掉，后续处理问题的成本会指数级上升。

站在工程角度，这些判断本质上都在回答同一个问题：当前上下文是什么？把这个问题散落到各处去回答，必然导致不一致。context-mode 的思路就是“收敛”——上下文的采集、识别、匹配全部收口到一处，业务侧不再关心判断细节。

1.2 常见方案的优缺点对比

在落地 context-mode 之前，我其实试过好几种方案。这里把它们放在一起对比，方便你理解为什么最终会走到 context-mode 这条路上。

环境变量方案最省事，但只适合“脚本级”项目。Profile 方案在 Java 生态很好用，可一旦团队里同时有 Go、Node.js、Python 服务，就很难统一。配置中心的运维成本不是每个团队都愿意背。context-mode 更像是一种“代码层的设计模式”，它不依赖特定框架，也不需要额外的基础设施，只要团队认同“上下文要集中管理”这个原则，就能在不同语言里落地同一套设计思想。

1.3 context-mode 的设计目标

做 context-mode 不是一时兴起，我给它定了四个明确的目标。

第一，上下文采集统一。不管是环境变量、命令行参数、请求头还是部署平台的标签，都由 collect 阶段统一收进来，业务代码不直接接触原始变量。

第二，模式匹配可声明。规则用配置或数据描述，而不是散落的 if/else。看到一份规则列表，就能理解系统在什么情况下会进入什么模式。

第三，业务侧只声明需求。业务代码只表达“我想要 mock 数据”或“我需要 verbose 日志”，至于当前到底是不是测试环境，由 context-mode 判断。

第四，可观测、可测试。任何时候都能打印出“当前是什么模式、为什么匹配到这个模式、命中了哪条规则”。测试时也能轻松注入伪造的上下文，不需要真的去改环境变量。

这四个目标贯穿了后续的整个实现。如果你也经常被环境判断问题困扰，可以先对照这四个目标想想自己缺的是什么，再往下看具体实现。

2. 核心设计：上下文感知与模式匹配机制

2.1 上下文信息从哪里来

context-mode 的第一步是“采集”。我在实现中把上下文来源分成五类，每一类都有它的价值，也存在各自的盲区。

只用一个来源很容易出问题。我碰到过一个案例：某部署平台会自动覆盖NODE_ENV，导致开发者本地跑的NODE_ENV=development在联调环境里变成了production，排查了半天才发现是平台注入的。后来我们规定了一个原则：环境变量的权重最低，命令行参数和平台标签的权重最高。原因很简单，越靠近“本次运行意图”的信息越可靠。开发者在命令行手动指定的参数代表他的明确意图，平台标签是运维侧的权威标记，而环境变量可能被各种工具链无意间改动。

2.2 探测与归一化：把环境变成标准字段

采集到原始信息后，不能直接拿去做匹配。不同来源的信息格式千奇百怪，需要先归一化成标准字段。归一化要做两件事：改名和标准化取值。

改名是指把NODE_ENV、APP_ENV、DEPLOY_ENV这类同义变量统一映射为一个字段env。标准化取值是指把true/1/yes/on这类布尔值的不同写法统一转成标准布尔值，把api.example.com和api.example.com.这类域名差异去掉尾部点号。

interface RawContext { env?: string; hostname?: string; domain?: string; region?: string; tenantId?: string; argv: string[]; headers: Record<string, string>; labels: Record<string, string>; } interface NormalizedContext { env: string; hostname: string; domain: string; region: string; isCi: boolean; isLocalhost: boolean; runId?: string; }

归一化函数的核心逻辑是根据来源优先级依次取字段，后取的字段如果已经有值就不能被低优先级来源覆盖。这里有个细节经验：不要一上来就把所有来源绞在一起读取，而是把它们定义成独立 collector，每个 collector 负责一个来源，最后按优先级合并。这样新增一个来源时不需要改动主逻辑，只要加一个 collector 实现即可。

interface Collector { name: string; priority: number; collect(): Partial<RawContext>; }

2.3 模式匹配规则：精确、通配、正则的优先级算法

上下文归一化之后，就轮到规则引擎上场。模式匹配是整个 context-mode 最灵活的部分，我把规则设计成有序数组，每条规则包含名称、匹配条件、优先级和附加元数据。

interface ContextRule { name: string; match: { // 支持精确值、通配符、正则三类写法 env?: string | string[]; hostname?: string; domain?: string; region?: string; }; priority: number; meta?: Record<string, unknown>; }

匹配算法遵循“先收集所有可命中规则，再按优先级选取胜出规则”的思路。这里有个关键决策：为什么不选择“第一个命中就返回”？因为真实场景里可能存在“测试环境但命中本地方域名”的矛盾，如果使用先到先得，规则顺序稍变就会导致结果完全不同，排查起来非常痛苦。而收集所有命中后按优先级排序，再结合日志输出原因，可观测性会好很多。

function matchRule(rule: ContextRule, ctx: NormalizedContext): boolean { for (const [key, pattern] of Object.entries(rule.match)) { const actual = String((ctx as Record<string, string>)[key] ?? ''); const matched = Array.isArray(pattern) ? pattern.some((p) => matchPattern(actual, p)) : matchPattern(actual, pattern); if (!matched) return false; } return true; } function matchPattern(actual: string, pattern: string): boolean { if (pattern.startsWith('/') && pattern.endsWith('/')) { return new RegExp(pattern.slice(1, -1), 'i').test(actual); } if (pattern.includes('*')) { const regex = new RegExp( '^' + pattern.split('*').map(escapeRegExp).join('.*') + '$', 'i' ); return regex.test(actual); } return actual.toLowerCase() === pattern.toLowerCase(); }

实现时还踩了一个坑：通配符的转义必须做，否则规则里的.会被当成正则任意字符匹配，导致api.example.com匹配到apiXexampleXcom，极隐蔽。所以上面代码里escapeRegExp那一步不能省略，这是很多初版实现都容易漏掉的地方。

3. 落地实操：一个可复用的 context-mode 模块

3.1 整体模块结构与接口定义

纸上谈兵没什么意思，直接上一份可以在项目里用的模块设计。我用 TypeScript 写，但同样的结构用 Go 或 Python 也能照搬。

context-mode/ src/ index.ts // 对外入口，导出 createContextMode collector.ts // 采集器接口与默认采集器 normalize.ts // 归一化函数 rules.ts // 规则定义与示例规则 engine.ts // 匹配引擎 async.ts // 基于 AsyncLocalStorage 的上下文传递 examples/ cli-tool.ts // CLI 工具接入示例 api-service.ts // API 服务接入示例

对外接口设计得越简单越好。核心只有三件事：创建实例、解析上下文、把上下文注入异步链路。

interface ContextMode { resolve(): Promise<string>; getCurrentContext(): NormalizedContext | undefined; runWithContext<T>(ctx: Partial<RawContext>, fn: () => Promise<T>): Promise<T>; }

这个接口刻意把“规则”和“采集器”都放在了createContextMode参数里，目的是让模块本身保持纯粹。不同的项目可以传入不同的规则，但核心引擎不需要变化。我在实际使用时还会把resolve的返回结果缓存起来，并把缓存 TTL 默认设成 5 秒，避免每次请求都跑一遍完整采集和匹配逻辑。CLI 工具可以设更长，服务端建议设短一点，防止平台标签变动后长时间感知不到。

3.2 关键代码实现拆解

核心引擎的代码量其实不大，但每部分都有值得细说的点。先看 index.ts 里的实例创建逻辑：

import { AsyncLocalStorage } from 'async_hooks'; const asyncLocalStorage = new AsyncLocalStorage<NormalizedContext>(); export function createContextMode(options: { collectors: Collector[]; rules: ContextRule[]; }) { const { collectors, rules } = options; async function collect(): Promise<NormalizedContext> { const raw: RawContext = { argv: process.argv, headers: {}, labels: {} }; const sortedCollectors = [...collectors].sort( (a, b) => b.priority - a.priority ); for (const collector of sortedCollectors) { const part = await collector.collect(); // 只覆盖未定义字段，高优先级 collector 先执行，低优先级不能覆盖已有值 Object.assign(raw, Object.fromEntries( Object.entries(part).filter(([_, v]) => v !== undefined && v !== '') )); } return normalize(raw); } async function resolve(): Promise<string> { const ctx = await collect(); const hits = rules.map((rule) => ({ rule, matched: matchRule(rule, ctx), })); const matchedRules = hits .filter((hit) => hit.matched) .sort((a, b) => b.rule.priority - a.rule.priority); const winner = matchedRules[0]?.rule; // 把命中过程记录下来，方便排查“为什么进入了这个模式” const resolution = { winner: winner?.name ?? 'unknown', candidates: matchedRules.map((hit) => hit.rule.name), normalizedContext: ctx, }; asyncLocalStorage.enterWith(ctx); if (options.onResolve) { options.onResolve(resolution); } return resolution.winner; } return { resolve, getCurrentContext: () => asyncLocalStorage.getStore(), runWithContext: async <T>(ctx: Partial<RawContext>, fn: () => Promise<T>) => { const fullCtx = { ...(await collect()), ...normalize(ctx) }; return asyncLocalStorage.run(fullCtx, fn); }, }; }

collect阶段的“按优先级去重”是整个模块的基石。如果低优先级来源能覆盖高优先级字段，那么命令行参数就会被环境变量污染，所以这里用filter([_, v]) => ...的方式“只填充缺失字段”。这个设计我在注释里写得很清楚，后人维护时不会踩坑。

enterWith和run的区别值得注意。enterWith适合“全局只解析一次”的场景，比如 CLI 工具启动后调用一次contextMode.resolve()，后续流程所有地方都能通过getCurrentContext()拿到同一个上下文。run则适合服务端每个请求独立上下文的情况，每个请求都执行一个小范围的上下文注入，避免互相污染。

3.3 业务侧接入示例：多环境 CLI 工具

纸上得来终觉浅，用一个具体例子看怎么接。假设我要写一个部署 CLI 工具，需要根据目标环境决定连接哪套后端、是否开启 verbose 日志、运维审批是否跳过。

// deploy-cli.ts import { createContextMode } from './context-mode'; const contextMode = createContextMode({ collectors: buildCollectors(), // 包含 argv、env、platform labels 三个 collector rules: [ { name: 'local', match: { env: 'local' }, priority: 10 }, { name: 'test', match: { env: ['test', 'dev'] }, priority: 20 }, { name: 'prod', match: { env: 'prod', domain: /(api\.|admin\.)example\.com/ }, priority: 50, }, { name: 'prod-edge', match: { env: 'prod', domain: 'edge.example.com' }, priority: 60 }, ], }); async function main() { const mode = await contextMode.resolve(); const ctx = contextMode.getCurrentContext(); if (mode === 'local') { console.log('本地模式，后端使用 127.0.0.1:8080'); } else if (mode === 'test') { console.log('测试模式，后端使用 test.example.com'); } else { console.log('生产模式，后端使用 api.example.com'); } console.log(`命中规则: ${mode}, 运行环境: ${ctx?.env}, 平台域名: ${ctx?.domain}`); } main();

这里演示了 context-mode 最典型的收益点：CLI 里不用再写一堆if (ctx.env === 'production' && ctx.domain === 'edge...')，而是把规则集中在数组里。以后要加一个“生产灰度模式”，只需加一条规则，CLI 主体代码完全不用动。这在半年后再回头看，维护成本差距非常明显。

4. 常见问题与排查技巧实录

4.1 异步链路里上下文莫名丢失

这是接入异步 IO 密集型框架时最容易被坑到的问题。Node.js 里setTimeout、数据库回调、Promise 链都会切走异步上下文。如果某个模块在异步回调里取getCurrentContext()，拿到的是undefined，很多人第一反应是“context-mode 坏了”，其实是因为没有用AsyncLocalStorage.run包裹整个请求链路。

我的建议是：CLI 工具用enterWith一次性注入问题不大，但服务端一定要在入口处用runWithContext包裹整条链路。一个路由入口的做法是：

app.use(async (req, res, next) => { await contextMode.runWithContext( { headers: req.headers as Record<string, string>, argv: [], }, () => next() ); });

这样不管是中间件里还是业务函数里，只要是在这个请求链路内，getCurrentContext()都能拿到值。注意runWithContext的第一个参数建议只传“本次请求特有的信息”，环境变量、平台标签这类全局信息不必重复传，引擎会自动合并。

4.2 模式误匹配：域名、大小写与别名

我用 context-mode 之后遇到的第二个大坑是域名误匹配。测试环境的域名长这样：api-test.example.com，生产环境是api.example.com。我用include: ':test.'想识别测试环境，结果有一台机器 hostname 恰好是build-test-virtual-01，也被识别成了测试环境，导致生产环境的部署脚本走了测试分支。

排查方法很简单：把resolution对象打印出来看命中了哪些规则。我建议默认把“命中痕迹”输出到 stderr，或者为模式识别单独建一个日志文件。CI/CD 流水线里这个信息尤其值钱，能直接看出部署到生产环境的工具为什么选择了本地模式。

另一个常见问题是大小写。有的平台注入的ENV=Prod，规则里写的是prod，严格匹配就漏了。我的匹配策略默认对字符串比较做了toLowerCase()，但正则匹配时需要人为注意，建议在规则书写规范里统一要求小写，同时在归一化阶段把所有来源的字符串全部转小写。

4.3 过度自动化导致的“看不清当前模式”

context-mode 最被诟病的一点是：它把判断藏起来了。过去代码里写着if (isProd)，一眼能看懂；现在变成“规则列表里某条规则把 env 和 domain 组合判定成了 prod”，新人看起来容易懵。这个问题我从一开始就有意识在设计层面对抗，就是强调“可观测性”。

我要求所有接入 context-mode 的项目必须提供一个“诊断模式”。在 CLI 里是--context:inspect，在服务端是某个 Debug Header，访问后直接返回当前请求上下文、命中规则列表、未命中但部分匹配的规则列表。这样当有人问“为什么这个环境走了生产模式？”时，去诊断接口拉一份报告就行，完全不需要人肉翻代码。

$ deploy-cli --context:inspect 选中模式: prod 命中的规则: - prod (env=prod, domain=api.example.com 精确匹配) - prod-edge (env=prod, domain=edge.example.com 未命中) 当前上下文: env: production domain: api.example.com region: ap-southeast-1

这段报告设计成“给新人看也能秒懂”，是我在实践中觉得投入产出比最高的一项工作。

4.4 效率与安全：缓存、敏感信息和可观测性

模式匹配本身不重，但每次都把环境变量、命令行参数、响应头全部扫一遍也不是零成本。尤其服务端每个请求进来都跑一遍完整采集，性能损耗容易被放大。我实际用下来有两个优化手段：一是把“全局来源”和“请求来源”分开，环境变量、平台标签这些全局信息每 5 秒采集一次并缓存，请求头、查询参数这类请求级信息每请求单独采集；二是给高频场景直接加短路逻辑，比如某个请求头已经显式写了x-context-mode: prod，就不必再去匹配规则，直接采用显式模式并打日志。

安全方面，上下文信息可能包含敏感数据。采集时要有边界意识：环境变量里可能藏了数据库密码或 API Token，绝不能全部塞进上下文对象。我的处理方式是维护一张“采集字段白名单”，只有规则需要用到的字段才进上下文。打印诊断信息时也要做脱敏，凡是键名里包含token、password、secret的字段一律替换成***，避免诊断接口不小心变成泄密接口。

5. 从 context-mode 还可以延伸出哪些玩法

5.1 从单机到分布式：上下文怎么跨服务传递

context-mode 在单进程内的方案已经能解决大部分问题，但到了微服务环境，一个调用链经过三四个服务，如果每个服务各自采集上下文，模式判断结果可能不一致。A 服务认为当前是测试环境，B 服务因为收到的是内网域名，判断成了生产环境，整个联调就会被这种不一致拖垮。

解决思路是增加一个“透传层”。服务入口从请求头读取x-context-mode或x-context，如果存在，就把它作为最高优先级条件，直接决定当前模式；如果不存在，才动用本地的 collectors 和 rules 去自识别。这样网关或入口服务识别一次，下游信任这个结果，链路各环节的模式认知保持一致。当然，信任外来 Header 存在伪造风险，所以内网服务之间可以在网关层对 Header 做清洗，外部请求一律剥掉，只允许内部服务调用时写入。

5.2 给规则系统加上热更新能力

规则写在代码里简单直观，但也有不好改的问题。生产环境想临时把某个域名划到“灰度模式”，改代码发版可能要走半个小时的流水线。这时可以把规则列表放到配置中心或远端 JSON 里，context-mode 定期拉取并本地缓存。规则文件的格式保持和代码里的定义一样，只是从本地数组变成了远端 JSON。

实现热更新后一定要加版本号和校验和。我第一次做远端规则时没校验，配置中心更新到一半，规则拉回来是残缺的，所有模式匹配全部失败，影响范围非常大。后续改成“先下载完整文件，校验通过后再整体替换内存规则”，配合灰度发布，再也没出过类似问题。

5.3 我在实际项目中的使用体会与建议

如果你准备引入 context-mode，我的建议是不要第一个版本就追求大而全。先挑一个最疼的场景切入，比如部署 CLI 或多环境 API 服务的模式识别，把采集器、规则、诊断这三个部分跑通，再逐步扩展。

我自己的一个教训是：规则命名如果不规范，时间长了也会变成“新式垃圾代码”。我见过有人给规则起名叫rule_1、rule_2，后期根本无法维护。规则名其实就是系统里的“业务词汇”，最好和领域术语保持一致，比如local-dev、test-env、pre-prod、prod-edge，这样诊断报告才能被非技术同事看懂。

我始终认为，context-mode 本质上不是在解决“环境变量怎么读”这种技术问题，而是在帮团队把对运行场景的“隐形假设”显性化。它不复杂，却能在很长一段时间里保护你不被一堆散落的 if/else 折磨。希望这篇文章的思路和代码能给你一些启发，哪怕只拿走诊断报告那一招，也算不虚此行了。