1. 从“context-mode”这个词说起：它到底在解决什么问题
第一次看到“context-mode”这个标题，很多人会下意识地把它当成某个框架里的配置项，或者某个库的开关参数。但如果你真的在工程一线待过几年，就会发现这个词背后藏着一个非常朴素、却又极其容易被忽视的诉求：同一套逻辑，在不同上下文里需要表现出不同的行为，而这件事如果处理不好，代码会迅速腐烂成一团乱麻。
我最早接触类似概念，是在做一个多端复用的业务模块时。同一段数据处理逻辑，在后台管理端需要返回完整字段，在移动端需要裁剪掉敏感信息，在定时任务里又需要走批量模式。当时团队的做法是写三个函数，各自复制粘贴，然后靠注释区分。结果就是改一个字段要改三处，漏一处就出线上问题。后来我们引入了一个显式的“上下文模式”参数，把差异点收敛到一个地方，代码量直接砍掉一半，维护成本更是断崖式下降。
所以“context-mode”本质上不是一个具体的技术名词，而是一种设计思路：把“当前处于什么场景”这件事显式化、参数化，让同一套核心逻辑根据上下文切换行为，而不是靠复制代码或者到处写 if-else 来打补丁。它适合所有正在被“多场景复用”折磨的开发者，无论你写的是前端组件、后端服务，还是数据处理脚本。
这篇文章我会从实际工程角度，把 context-mode 这个思路拆开讲透：它为什么会出现、核心机制怎么设计、落地时有哪些坑、以及我踩过之后总结出来的实操经验。全文不依赖任何特定框架，你可以把它套用到自己手头的项目里。
2. 为什么“复制粘贴 + if-else”最终一定会失控
2.1 多场景复用的三种典型写法及其代价
在讲 context-mode 之前，先看看大多数人是怎么处理多场景的。我把常见的做法归成三类，每一类我都实际用过，也都付出过代价。
第一种：复制粘贴派。需要移动端版本？把原函数复制一份，改改字段返回。需要批量版本？再复制一份。这种写法在场景只有两三个的时候看起来还行，但场景数量是乘法增长的——端类型乘以业务模式乘以权限等级，很快就变成十几个近似函数。改一个公共逻辑要同步改十几处，漏掉任何一处就是线上事故。
第二种：if-else 派。不复制了，在一个函数里根据传入的标志位判断。这比复制粘贴进步了一点，但问题是判断逻辑会渗透到函数的每一个角落。你会在参数校验里看到if (mode === 'batch')，在字段组装里看到if (mode === 'mobile')，在日志里又看到一次。函数越来越长，圈复杂度飙升，测试用例要覆盖所有分支组合，写测试的人想辞职。
第三种：继承/策略派。用基类加子类，或者策略模式把差异抽出来。这是相对成熟的做法，但很多团队用不好，因为抽象层次没设计对。基类里塞了太多“可能被覆盖”的方法，子类只覆盖其中一两个，结果读代码的人要在基类和子类之间反复跳转才能理解一个完整流程。
这三种写法的共同问题是：上下文信息是隐式的、分散的。你不知道当前到底处于什么模式，只能靠读代码去推断。而 context-mode 要做的第一件事，就是把这个信息变成一个显式的、贯穿始终的对象。
2.2 上下文爆炸：场景组合为什么是乘法而不是加法
很多人低估了场景组合的复杂度。假设你有三个维度：运行环境（开发/测试/生产）、调用来源（Web/移动/第三方）、业务模式（实时/批量）。看起来只有 3+3+2=8 个选项，但实际组合是 3×3×2=18 种。如果每个组合都有细微差异，靠 if-else 去覆盖就是灾难。
我做过一个统计，在一个中等规模的服务里，因为场景组合导致的 bug 占总 bug 数的三成以上，而且这类 bug 特别隐蔽——因为它在某个特定组合下才出现，本地开发环境根本复现不了。context-mode 的价值就在于，它强迫你在设计阶段就把这些维度想清楚，而不是等到 bug 出现了再打补丁。
提示：如果你现在手里的代码已经出现了“同一个函数里超过三个模式判断”的情况，那就是该重构的信号了。不要等到它变成技术债再动手。
2.3 一个真实的重构案例：从 800 行到 200 行
我经手过一个数据处理模块，原始版本 800 多行，里面充斥着各种模式判断。重构时我做的第一件事不是改代码，而是把所有出现过的模式组合列出来，做成一张表。结果发现实际有效的组合只有 6 种，其余都是历史遗留的死分支。
然后我把这 6 种组合抽象成一个 context 对象，包含source、mode、permission三个字段。核心逻辑只读这个对象，不再读散落的标志位。差异部分用一张映射表来配置，而不是写 if-else。重构后代码降到 200 行左右，而且新增一种模式只需要在映射表里加一行配置。
这个案例说明，context-mode 的核心不是某个具体实现，而是先梳理清楚上下文维度，再决定怎么表达。梳理这一步比写代码重要得多。
3. context-mode 的核心机制拆解：上下文对象该怎么设计
3.1 上下文对象的三个必备字段
一个能用的 context 对象，至少要包含三类信息，我称之为“三要素”。
第一类是来源标识（source），说明这次调用是从哪来的。是 Web 请求、移动端调用、定时任务，还是内部服务调用。这个字段决定了对外暴露的字段范围、限流策略、日志级别。
第二类是行为模式（mode），说明这次调用要做什么。是实时查询、批量导出、还是预计算。这个字段决定了走哪条执行路径、用不用缓存、批量大小是多少。
第三类是权限等级（permission），说明调用方有什么权限。这个字段决定了数据脱敏程度、可访问的资源范围。
这三个字段不是随便定的，它们对应的是三个正交的维度：谁在调、要做什么、能看什么。把这三个维度固定下来，大部分场景差异都能被覆盖。如果你的项目还有特殊维度，比如租户隔离、灰度分组，可以再加字段，但不要超过五个，否则 context 对象本身就会变成新的复杂度来源。
3.2 用不可变对象承载上下文，避免“中途被改”
context 对象一旦创建，就应该当成不可变的。我见过太多项目，context 在传递过程中被某个中间件偷偷改了字段，导致下游逻辑拿到的是被污染的数据。这种 bug 极难排查，因为问题现场和出错现场隔了好几层调用。
正确做法是：context 创建后冻结，任何需要变体的地方都创建一个新对象，而不是原地修改。在 JavaScript 里可以用Object.freeze，在 Python 里可以用dataclass(frozen=True)，在 Java 里可以用不可变类。多创建几个对象的开销，远小于排查一个上下文污染 bug 的成本。
from dataclasses import dataclass @dataclass(frozen=True) class Context: source: str mode: str permission: str def derive(self, **kwargs): return Context( source=kwargs.get('source', self.source), mode=kwargs.get('mode', self.mode), permission=kwargs.get('permission', self.permission), )上面这段代码展示了不可变 context 的基本写法。derive方法用来派生新上下文，而不是修改原对象。这样任何一层拿到 context 后，都能确信它的值不会被别人改掉。
3.3 上下文如何贯穿调用链：显式传递 vs 隐式存储
context 怎么在调用链里传递，是个有争议的话题。两种主流做法：显式传参和隐式存储（比如线程本地变量、异步上下文变量）。
显式传参的好处是清晰，任何函数签名里带 context 的，你都知道它依赖上下文。坏处是参数列表变长，中间层函数即使不用 context 也得往下传，显得啰嗦。
隐式存储的好处是调用方无感，坏处是“魔法”——你读一个函数看不出它依赖上下文，调试时也难追踪。
我的经验是：核心业务逻辑用显式传参，基础设施层（日志、监控、鉴权）用隐式存储。因为核心逻辑的上下文依赖是业务语义的一部分，应该显式表达；而基础设施层的上下文是横切关注点，隐式存储更合适。
注意：隐式存储一定要在请求入口处设置、在请求出口处清理，否则在长连接或线程池场景下会发生上下文串号，这是非常经典的线上事故。
4. 落地实操：把 context-mode 装进现有项目的完整步骤
4.1 第一步：盘点现有代码里的模式判断
不要一上来就改代码。先做盘点。把项目里所有跟“模式”“场景”“类型”相关的判断找出来，可以用全局搜索关键词的方式，比如搜mode、type、source、platform、env这些词。
把搜到的判断点记录到一张表里，包含：文件位置、判断条件、影响的行为。这张表就是你后续重构的地图。我做过一次这样的盘点，在一个十万行的项目里找到了 200 多处模式判断，其中真正必要的只有 40 多处，其余都是可以合并或删除的。
盘点完成后，你会对“到底有几种上下文”有一个清晰的认识。这时候再设计 context 对象，就不会拍脑袋。
4.2 第二步：定义 context 对象和模式枚举
根据盘点结果，定义 context 的字段和每个字段的取值。取值一定要用枚举，不要用裸字符串。裸字符串的问题是拼写错误不会被发现，而且 IDE 无法提示。
const Source = Object.freeze({ WEB: 'web', MOBILE: 'mobile', JOB: 'job', INTERNAL: 'internal', }); const Mode = Object.freeze({ REALTIME: 'realtime', BATCH: 'batch', EXPORT: 'export', }); function createContext({ source, mode, permission }) { if (!Object.values(Source).includes(source)) { throw new Error(`invalid source: ${source}`); } if (!Object.values(Mode).includes(mode)) { throw new Error(`invalid mode: ${mode}`); } return Object.freeze({ source, mode, permission }); }这段代码的关键点是在创建时就校验合法性。非法上下文应该在入口处就被拦截，而不是等到业务逻辑深处才报错。这样能把问题暴露在离现场最近的地方。
4.3 第三步：把差异点收敛到映射表
context-mode 最核心的落地技巧，是用映射表代替 if-else。把“什么上下文对应什么行为”写成配置，而不是写成代码分支。
const FIELD_POLICY = { [Source.WEB]: ['id', 'name', 'email', 'createdAt'], [Source.MOBILE]: ['id', 'name'], [Source.INTERNAL]: ['id', 'name', 'email', 'createdAt', 'internalNote'], }; function pickFields(record, context) { const fields = FIELD_POLICY[context.source] || []; return fields.reduce((acc, key) => { acc[key] = record[key]; return acc; }, {}); }映射表的好处是：新增一种来源，只需要加一行配置，不用改函数逻辑。而且这张表本身就是最好的文档，读代码的人一眼就能看出每种来源返回哪些字段。
4.4 第四步：用中间件统一注入上下文
在 Web 框架里，context 的创建应该放在中间件层。中间件从请求头、路由、用户身份里提取信息，组装成 context，挂到请求对象上。业务代码从请求对象里取 context，而不是自己拼。
function contextMiddleware(req, res, next) { const source = req.headers['x-client-type'] || Source.WEB; const mode = req.query.mode || Mode.REALTIME; const permission = req.user ? req.user.level : 'guest'; req.context = createContext({ source, mode, permission }); next(); }中间件的好处是统一入口、统一校验、统一默认值。业务代码不需要关心 context 从哪来，只需要关心怎么用。这样也方便做全局的日志埋点和监控。
5. 踩坑实录：context-mode 落地时最容易翻车的四个地方
5.1 坑一：上下文默认值埋下的隐性 bug
中间件里给 context 字段设默认值，看起来是贴心设计，实际上是隐患。比如上面代码里mode默认是realtime，如果某个调用方忘了传 mode，它就会静默地走实时模式，而不是报错。如果这个调用本该走批量模式，就会造成性能问题甚至数据错误。
我的做法是：对业务关键的字段不设默认值，缺失就报错。只有那些确实有合理默认的字段才设默认值，比如日志级别默认 info。判断标准是：这个字段缺失时，系统能不能给出一个“明显正确”的行为？如果不能，就不要设默认。
5.2 坑二：上下文在异步任务里丢失
这是最经典的坑。在 Web 请求里 context 挂在请求对象上，一切正常。但一旦把任务丢到异步队列或者线程池里，请求对象没了，context 也就丢了。异步任务里拿不到 context，要么报错，要么拿到一个错误的默认值。
解决方案是：在任务入队时把 context 序列化，出队时反序列化重建。不要试图在线程间共享 context 对象，因为不可变对象跨线程传递需要序列化支持。把 context 当成任务 payload 的一部分，跟着任务走。
def enqueue_task(payload, context): task = { 'payload': payload, 'context': { 'source': context.source, 'mode': context.mode, 'permission': context.permission, }, } queue.put(task) def worker(): task = queue.get() context = create_context(**task['context']) process(task['payload'], context)5.3 坑三：模式判断散落在 SQL 和缓存键里
context-mode 的差异不只体现在代码逻辑里，还体现在 SQL 查询和缓存键上。比如批量模式和实时模式的查询语句可能不同，不同来源的缓存键必须隔离。如果只在代码层做了 context 处理，忘了在 SQL 和缓存层同步，就会出现数据串号。
我踩过一次这样的坑：移动端和 Web 端共用了一个缓存键，结果移动端拿到了 Web 端的完整字段，敏感信息泄露。修复方式是把 context 的关键字段拼进缓存键，比如user:${id}:${source}:${mode}。SQL 层同理，不同模式走不同的查询构造器。
5.4 坑四：上下文维度膨胀导致组合爆炸
前面说过 context 字段不要超过五个，但实际项目中很容易失控。今天加一个tenant，明天加一个gray，后天加一个region，很快就变成十几个字段，组合数爆炸，映射表维护不动。
控制方法是：区分“上下文维度”和“业务参数”。上下文维度是影响全局行为的，业务参数是影响单次调用的。比如租户 ID 如果影响数据隔离和权限，那是上下文维度；如果只是查询条件，那是业务参数，不该进 context。每次想往 context 里加字段时，先问一句：这个字段会影响多个不相关模块的行为吗？如果只影响一两个地方，那它不配进 context。
6. 进阶玩法：让 context-mode 从“能用”到“好用”
6.1 用 context 驱动可观测性：日志和指标自动带上下文
context 一旦贯穿调用链，就可以拿来做可观测性。在日志里自动带上 source、mode、permission，排查问题时可以按这些维度过滤。在指标里按 context 维度打标签，可以快速定位是哪个来源、哪种模式出了问题。
function logWithContext(level, message, context, extra = {}) { console.log(JSON.stringify({ level, message, source: context.source, mode: context.mode, permission: context.permission, ...extra, timestamp: Date.now(), })); }这样打出来的日志是结构化的，可以直接被日志系统解析和聚合。我做过对比，加了 context 维度后，线上问题定位时间平均缩短了一半以上，因为不用再靠猜“这个请求是从哪来的”。
6.2 用 context 做灰度：按来源和模式逐步放量
灰度发布是 context-mode 的天然应用场景。你可以按 source 灰度，先让内部调用走新逻辑，再让 Web 端走，最后让移动端走。也可以按 mode 灰度，先让批量模式走新逻辑，验证稳定后再让实时模式走。
实现方式是在 context 里加一个version字段，或者在映射表里按 context 决定走新逻辑还是旧逻辑。这样灰度策略和业务逻辑解耦，切换灰度只需要改配置，不用改代码。
6.3 用 context 做测试：一个函数覆盖所有模式
context-mode 让测试变得简单。因为所有模式差异都收敛在映射表里，你可以写一个参数化测试，遍历所有 context 组合，验证每种组合的输出是否符合预期。
const cases = [ { source: Source.WEB, mode: Mode.REALTIME, expected: ['id', 'name', 'email', 'createdAt'] }, { source: Source.MOBILE, mode: Mode.REALTIME, expected: ['id', 'name'] }, { source: Source.INTERNAL, mode: Mode.BATCH, expected: ['id', 'name', 'email', 'createdAt', 'internalNote'] }, ]; cases.forEach(({ source, mode, expected }) => { test(`${source}-${mode}`, () => { const context = createContext({ source, mode, permission: 'user' }); const result = pickFields(sampleRecord, context); expect(Object.keys(result)).toEqual(expected); }); });这种测试写起来快，覆盖全，而且新增模式时只需要加一行用例。比手写一堆 if-else 测试高效得多。
7. 我个人在实际项目中的几点体会
context-mode 这个思路我用了好几年，从最初的小工具到后来的大型服务，越用越觉得它的价值不在技术本身，而在它强迫你在设计阶段就想清楚“到底有几种场景”。很多项目的混乱，根源不是代码写得差，而是场景没想清楚就开始写，写到一半发现漏了一种，再打补丁，补丁叠补丁，最后谁也说不清到底有几种模式。
我现在接手一个新项目，第一件事就是问：这个系统有几种调用来源？几种运行模式？几种权限等级？把这三个问题回答清楚，context 对象的雏形就有了。回答不清楚，那就先别写代码，先把场景梳理明白。
另外一点体会是，context-mode 不要过度设计。我见过有人把 context 做成一个庞大的继承体系，每个字段一个子类，结果比原来的 if-else 还难维护。context 应该是一个扁平的、不可变的数据对象，差异用映射表表达，不要用继承。简单直接，才是它最大的优势。
最后分享一个小技巧：在项目里加一个 context 校验的单元测试，确保所有合法的 context 组合都能被正确处理，所有非法的 context 组合都会被拒绝。这个测试跑起来很快，但能挡住大部分因为上下文错误导致的线上问题。我把它加进 CI 之后，相关 bug 基本绝迹了。
