context-mode 设计实践：用显式上下文模式替代散落的条件判断

1. 从“context-mode”这个标题说起：它到底在解决什么问题

第一次看到“context-mode”这个词，我脑子里蹦出来的不是某个具体框架，而是一类反复出现的工程痛点：同一个系统里，代码要在完全不同的运行环境、不同的调用链路、不同的数据形态之间来回切换，而每次切换都伴随着一堆 if-else、配置分支和隐式约定。时间一长，没人说得清当前到底跑在哪种“模式”下，出了问题只能靠猜。

我把它理解成一种**上下文模式（context mode）**的设计思路：把“当前处于什么场景、该用哪套行为”这件事，从散落各处的条件判断里抽出来，收敛成一个显式的、可枚举、可切换、可观测的状态。它不是一个具体的库，更像是一种架构约定，落地形态可以是前端的状态机、后端的请求上下文、AI 应用里的会话模式，也可以是构建工具里的编译模式。

它能做的事情很实在：让同一份核心逻辑，在不同上下文下表现出不同但可预期的行为，同时把“为什么是这个行为”这件事变得可追溯。解决的正是那种“代码越写越像迷宫、新人接手要读三天、线上问题定位全靠日志考古”的老大难。

适合谁来参考？如果你正在做多端适配、多租户系统、AI 对话应用、或者任何需要“一套内核、多种表现”的项目，这篇内容应该能给你一些可以直接抄的思路。哪怕你只是被满屏的if (env === 'xxx')折磨过，也值得往下看。

2. 内容整体设计与思路拆解

2.1 为什么要把“模式”显式化

先说一个我踩过的坑。早些年做一个多端项目，同一套业务逻辑要跑在移动端、桌面端和嵌入式的 WebView 里。最开始的做法很“自然”：到处写if (platform === 'mobile')。刚开始还行，等到平台从 3 个变成 6 个，每个平台又有自己的子模式（比如移动端分横屏竖屏、桌面端分主窗口和悬浮窗），条件判断直接爆炸。最要命的是，某个行为到底在哪个平台生效，得全局搜索才能确认。

后来我们把它改成显式的 context mode：定义一组有限的模式枚举，每个模式绑定一套行为策略，运行时只认当前模式，不再散落判断。改完之后，新增一个平台从“改 20 个文件”变成“加一个模式定义 + 一套策略”。这就是显式化的价值——把隐式的、分散的上下文，变成显式的、集中的状态。

从设计角度看，这背后其实是三个原则在起作用。第一是单一事实来源：当前模式只有一个地方说了算，不允许各处自行推断。第二是开闭原则：新增模式是扩展，不是修改已有逻辑。第三是可观测性：当前处于什么模式，能直接打印出来、上报出去，而不是靠推理。

2.2 方案选型：状态机、策略模式还是上下文对象

落地 context-mode 有几种常见路子，我分别说说适用场景和取舍。

状态机适合模式之间有明确迁移规则的场景。比如一个订单系统，从“待支付”到“已支付”到“已发货”，模式切换有严格顺序，非法迁移要拦截。用状态机的好处是迁移路径一目了然，坏处是如果模式之间可以任意切换，状态机会变得很重。

策略模式适合模式之间相互独立、切换无副作用的场景。比如不同支付渠道的计费策略，选哪个模式就执行哪套逻辑，互不干扰。这是最轻量的做法，我大多数时候首选它。

上下文对象适合模式需要携带大量运行时数据的场景。比如 AI 对话应用，每个会话有自己的历史、人设、工具集，这些都属于“上下文”，模式只是上下文的一个字段。这时候把上下文整体封装成一个对象，模式作为其中的枚举，读写都走这个对象。

我的经验是：先判断模式之间有没有迁移约束，有就用状态机，没有就用策略模式；如果模式还绑定了大量运行时数据，就再包一层上下文对象。不要一上来就上最重的方案，很多项目其实策略模式就够了。

2.3 核心关键词的落点：context 与 mode 的边界

这里有个容易混淆的点：context（上下文）和 mode（模式）到底怎么分。我的划分标准是——context 是“数据”，mode 是“行为”。

context 回答的是“现在有哪些信息可用”：当前用户是谁、请求来自哪个端、会话历史有多长、配置项是什么。mode 回答的是“基于这些信息，我该怎么做”：用哪套渲染逻辑、调哪个后端接口、走哪条处理链路。

举个具体例子。一个内容平台，context 里可能有userTier（用户等级）、deviceType（设备类型）、networkQuality（网络质量）。而 mode 可能是lite（精简模式）、standard（标准模式）、rich（富媒体模式）。决定用哪个 mode，是读 context 算出来的；但一旦 mode 定了，后续行为就只看 mode，不再反复读 context。这个边界划清楚，代码就不会乱。

注意：很多人会把 mode 直接塞进 context 里当普通字段，然后到处读。这样做的后果是 mode 的“行为契约”被稀释了，又退回到散落判断的老路。mode 应该是 context 的“输出”，而不是“输入”。

3. 核心细节解析与实操要点

3.1 模式枚举的设计：宁少勿多，宁清晰勿模糊

设计模式枚举时，我见过两种极端。一种是模式太少，一个default包打天下，结果里面又是一堆判断；另一种是模式太多，十几个枚举值，彼此差异极小，维护起来头大。

我的建议是从实际行为差异出发，而不是从业务概念出发。判断标准很简单：如果两个模式的行为差异小于 20%，就合并；如果某个模式的行为需要超过 3 个条件才能描述清楚，就拆分。

具体操作上，我会先列一张表，把每个候选模式对应的行为差异写清楚。比如：

这张表一拉出来，模式之间的边界就清楚了。如果某两行几乎一样，直接合并。如果某一行描述不清，说明这个模式还没想明白，先别加。

实操心得：模式枚举的命名要体现“行为意图”，不要用type1、type2这种。用lite、standard、rich这种能自解释的名字，半年后回来看还能秒懂。

3.2 模式切换的触发时机与幂等性

模式切换最容易出问题的地方是切换时机和幂等性。我遇到过因为模式切换没做幂等，导致同一模式下重复初始化、资源泄漏的事故。

先说触发时机。常见的触发点有三类：启动时确定（比如根据设备能力选模式）、运行时动态切换（比如网络变差自动降级）、外部指令切换（比如用户手动选择）。启动时确定最简单，运行时切换最复杂，因为要考虑切换过程中的状态一致性。

我的做法是：切换只改一个“期望模式”字段，实际生效由统一的调度器处理。也就是说，业务代码只负责说“我想切到 lite”，至于什么时候切、切换过程中怎么过渡，交给调度器。这样业务代码不关心切换细节，调度器可以统一做幂等、做过渡、做回滚。

幂等性的实现很简单：调度器每次收到切换请求，先比对当前模式和目标模式，相同就直接返回，不同才执行切换。切换过程用一把锁或者一个标志位保护，防止并发切换。

// 简化的模式调度器示意 class ModeScheduler { constructor(initialMode) { this.currentMode = initialMode; this.switching = false; } async switchTo(targetMode) { if (targetMode === this.currentMode) return; // 幂等 if (this.switching) return; // 防并发 this.switching = true; try { await this.exitMode(this.currentMode); await this.enterMode(targetMode); this.currentMode = targetMode; } finally { this.switching = false; } } }

这段代码不复杂，但能挡掉 80% 的切换类 bug。关键点在于exitMode和enterMode要成对出现，且enterMode失败时要能回滚。

3.3 模式与配置的解耦：别让配置污染模式

另一个常见坑是把配置和模式混在一起。比如lite模式下某个参数是 10，standard模式下是 20，于是代码里写if (mode === 'lite') param = 10。这样做的后果是，每加一个模式就要改一遍参数逻辑，配置和模式死死绑在一起。

更好的做法是把参数抽成配置表，模式只负责选表。比如：

const MODE_CONFIG = { lite: { batchSize: 10, timeout: 5000, retry: 1 }, standard: { batchSize: 20, timeout: 3000, retry: 2 }, rich: { batchSize: 50, timeout: 2000, retry: 3 }, };

业务代码只读MODE_CONFIG[currentMode].batchSize，不关心具体值。这样调整参数只改配置表，加模式只加一行，逻辑代码完全不动。这个解耦看起来小，但在长期维护里省下的时间非常可观。

注意：配置表要集中管理，不要散落在多个文件里。我习惯放在一个mode-config.js里，所有模式相关参数一目了然。如果参数特别多，可以按模式拆成多个文件，但入口要统一。

4. 实操过程与核心环节实现

4.1 从零搭建一个 context-mode 骨架

下面我以一个“多端内容渲染”的场景为例，完整走一遍搭建过程。这个场景很典型：同一份内容数据，要在不同端、不同网络条件下用不同方式渲染。

第一步，定义模式枚举和配置表。

// modes.js export const MODES = { LITE: 'lite', STANDARD: 'standard', RICH: 'rich', }; export const MODE_CONFIG = { [MODES.LITE]: { renderer: 'text', imageQuality: 'low', animation: false, batchSize: 10, }, [MODES.STANDARD]: { renderer: 'mixed', imageQuality: 'medium', animation: true, batchSize: 20, }, [MODES.RICH]: { renderer: 'media', imageQuality: 'high', animation: true, batchSize: 50, }, };

第二步，写一个模式决策器，根据 context 算出 mode。

// mode-resolver.js import { MODES } from './modes'; export function resolveMode(context) { const { deviceType, networkQuality, userPreference } = context; // 用户手动指定优先 if (userPreference && Object.values(MODES).includes(userPreference)) { return userPreference; } // 弱网或低端设备降级 if (networkQuality === 'poor' || deviceType === 'low-end') { return MODES.LITE; } // 高性能设备且网络良好，用富媒体 if (deviceType === 'high-end' && networkQuality === 'good') { return MODES.RICH; } return MODES.STANDARD; }

这个决策器的逻辑很直白，但关键在于它是唯一的决策点。所有地方想知道当前模式，都调这个函数，不允许自己判断。

第三步，写模式调度器，处理切换。

// mode-scheduler.js import { MODE_CONFIG } from './modes'; export class ModeScheduler { constructor(initialMode, hooks = {}) { this.currentMode = initialMode; this.hooks = hooks; this.switching = false; } get config() { return MODE_CONFIG[this.currentMode]; } async switchTo(targetMode) { if (targetMode === this.currentMode) return; if (this.switching) return; this.switching = true; try { if (this.hooks.onExit) await this.hooks.onExit(this.currentMode); if (this.hooks.onEnter) await this.hooks.onEnter(targetMode); this.currentMode = targetMode; } finally { this.switching = false; } } }

第四步，业务代码只依赖调度器，不依赖具体模式。

// renderer.js export function renderContent(scheduler, contentList) { const { renderer, batchSize, animation } = scheduler.config; const batches = chunk(contentList, batchSize); batches.forEach((batch) => { switch (renderer) { case 'text': renderTextOnly(batch); break; case 'mixed': renderMixed(batch, { animation }); break; case 'media': renderMedia(batch, { animation }); break; } }); }

到这里，骨架就搭完了。整个链路是：context 进 → resolver 算出 mode → scheduler 持有 mode 和 config → 业务代码读 config 执行。每一层职责清晰，加模式、改参数、调决策逻辑，都只动一个地方。

4.2 参数计算：batchSize 和 timeout 怎么定

上面配置表里的batchSize、timeout这些值不是拍脑袋定的，得根据实际场景算。我拿batchSize举例。

假设lite模式跑在低端设备上，单条内容渲染耗时约 5ms，一帧预算 16ms，那么一批最多渲染 3 条才能不掉帧。但考虑到批量渲染有固定开销（比如创建容器约 10ms），实际一批渲染 10 条，总耗时 10×5+10=60ms，分摊到多帧里完成，用户感知不到卡顿。所以lite的batchSize定 10 是合理的。

standard模式设备性能好一些，单条 3ms，固定开销 8ms，一批 20 条总耗时 68ms，同样可接受。rich模式单条 2ms，固定开销 5ms，一批 50 条总耗时 105ms，但因为富媒体本身渲染就重，用户对加载有预期，所以可以接受。

timeout的算法类似：lite模式网络差，超时给宽一点，5000ms；standard给 3000ms；rich模式网络好，2000ms 足够。这些值上线后还要根据真实监控数据微调，但初始值这么算出来，比随便填靠谱得多。

实操心得：参数初始值一定要有计算依据，哪怕粗糙。这样上线后调参有基准，不会越调越乱。我习惯在配置表旁边写注释，说明每个值的计算逻辑，方便后人。

4.3 模式切换的现场记录：一次弱网降级的完整过程

说一个真实场景。用户在rich模式下刷内容，突然进电梯，网络从 good 掉到 poor。这时候系统要自动降级到lite。

整个过程是这样的：网络监听器检测到质量变化，更新 context；context 变化触发 resolver 重新计算，得出lite；resolver 把结果推给 scheduler；scheduler 执行switchTo('lite')。

切换过程中，onExit钩子先停掉rich模式的动画和预加载，释放资源；onEnter钩子初始化lite模式的纯文本渲染器，调整 batchSize。切换完成后，后续渲染全部走lite配置。

这里有个细节：切换过程中正在渲染的内容怎么办。我的做法是让当前批次渲染完再切，不打断进行中的任务。具体实现是在 scheduler 里加一个pendingTasks计数，切换前等计数归零。这样用户不会看到内容渲染到一半突然变样。

async switchTo(targetMode) { if (targetMode === this.currentMode) return; if (this.switching) return; this.switching = true; try { await this.waitForPendingTasks(); // 等当前任务完成 if (this.hooks.onExit) await this.hooks.onExit(this.currentMode); if (this.hooks.onEnter) await this.hooks.onEnter(targetMode); this.currentMode = targetMode; } finally { this.switching = false; } }

这个waitForPendingTasks是很多实现会漏掉的点，但恰恰是体验好坏的关键。

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

5.1 模式不生效：从决策链一路查下去

模式不生效是最常见的问题，表现是“明明该用 lite，结果还是 standard”。排查思路是沿着决策链一路查：context 对不对 → resolver 逻辑对不对 → scheduler 有没有收到 → 业务代码读的是不是 scheduler.config。

我整理了一张速查表：

这张表我贴在团队 wiki 上，新人遇到问题先自查，能省不少沟通成本。

5.2 模式爆炸：什么时候该合并模式

模式爆炸的典型症状是：枚举值越来越多，每个模式的行为差异越来越小，维护成本直线上升。我见过一个项目有 12 个模式，其中 5 个的差异只是某个参数不同。

判断要不要合并，我的标准是：如果两个模式的差异可以用配置表表达，就不该是两个模式。比如lite和lite-plus只是 batchSize 不同，那应该合并成一个模式，batchSize 作为配置项。

合并的操作也简单：把差异参数抽到配置表，删掉多余枚举，resolver 里把对应分支合并。合并后代码量减少，理解成本降低，而且新增变体只需要加配置行，不用加模式。

注意：合并模式要谨慎，如果两个模式的行为差异涉及不同的代码路径（不只是参数），那还是保留为独立模式。判断标准是“差异是数据还是逻辑”，数据差异合并，逻辑差异保留。

5.3 模式与缓存的冲突：切换后读到旧数据

这个坑比较隐蔽。模式切换后，如果缓存没清理，业务代码可能读到上一个模式缓存的数据，导致行为不一致。比如rich模式缓存了高清图，切到lite后还读这个缓存，流量就白省了。

我的做法是缓存 key 带上模式标识。比如content:${mode}:${id}，这样不同模式的缓存天然隔离，切换后自动读新 key，不会串。代价是缓存命中率略降，但换来的是行为一致性，值得。

如果缓存不能带模式（比如共享的后端缓存），那就在onExit钩子里主动清理当前模式的缓存，onEnter时重新预热。这个操作要异步做，别阻塞切换。

5.4 模式的可观测性：怎么知道线上跑在哪个模式

线上问题排查时，最怕不知道用户当时处于什么模式。我的做法是把当前模式打进所有关键日志和上报。具体来说，日志里加一个mode字段，错误上报里也带，监控面板按模式维度拆分。

这样出问题时，能直接看到“lite 模式下错误率是 standard 的 3 倍”，定位方向立刻清晰。更进一步，可以在页面上加一个隐藏的模式指示器（比如连续点击某个区域显示当前模式），方便测试和客服排查。

// 日志封装示例 function logWithMode(scheduler, message, extra = {}) { console.log(JSON.stringify({ mode: scheduler.currentMode, message, ...extra, timestamp: Date.now(), })); }

这个习惯看起来小，但在真实故障排查里，能省下大量“猜模式”的时间。

6. 模式设计的进阶思考与个人体会

6.1 模式不是越多越好，而是越准越好

做了几个 context-mode 项目后，我最大的体会是：模式的价值在于准确，不在于数量。一个只有 3 个模式但每个都精准命中场景的系统，比一个有 10 个模式但边界模糊的系统好用得多。

精准的前提是想清楚每个模式“为谁服务、解决什么问题”。如果说不清，那这个模式就不该存在。我现在的习惯是，每加一个模式前先写一句话描述它的适用场景，写不出来就不加。

6.2 模式与降级：天然的好搭档

context-mode 和降级策略是天生一对。降级本质上就是“从高模式切到低模式”，而 context-mode 提供了现成的切换机制。把降级触发条件接到 resolver 里，降级就变成了模式切换的一个特例，不用单独写一套逻辑。

我在一个项目里就是这么做的：网络差、内存高、错误率高，三个条件任一触发就降级。因为复用了模式切换的幂等和过渡机制，降级过程很稳，没有出现切换类 bug。

6.3 给后来者的几句实在话

如果你正准备在项目里引入 context-mode，我的建议是：先小范围试点，别一上来就全量重构。挑一个条件判断最密集的模块，把它改成模式驱动，跑一段时间看效果。如果确实减少了复杂度、提升了可维护性，再逐步推广。

另外，模式的定义要跟着业务走，别为了“架构好看”硬造模式。业务需要几个模式就几个，不需要就不加。架构是服务业务的，不是反过来。

最后分享一个小技巧：把模式相关的所有文件放在一个目录下（比如src/modes/），包括枚举、配置、resolver、scheduler。这样模式的全貌一目了然，新人接手也能快速找到入口。这个目录结构上的小约定，长期看能省下不少找文件的时间。