「一语控物」的全部可测试性,来自一条看起来很偏执的规则: core/ 目录下绝对不允许出现 wx.—— 连 typeof wx 这种探测都不行。这条规则撑起了 325 个单元测试、 91.7% 的语句覆盖率,以及一个在未来可以搬去云端或任何宿主的业务核心。 这篇讲这条规则为什么这么硬,以及靠什么守住。

01为什么是一条红线

先看这个项目的分层里 core/ 装了什么:DAP 协议编解码、参数校验、 传输状态机、指令文法引擎、设备注册表、会话编排——全部正确性最关键的逻辑。 这些逻辑只有一个地方能被充分测试:Jest 在 Node 下直接跑。

而只要 core 里出现一次 wx.,测试就要 mock 全局 wx 对象。mock 一处不难,难的是从此以后:

  • 每个测试文件都要维护一份「wx 长什么样」的假象,假象和真平台的偏差没人负责;
  • core 的复用死刑——想把它搬进云函数或另一个宿主,先满地找 wx 调用;
  • 边界开始模糊,第二次 wx. 出现的心理成本比第一次低得多。

所以规则没有写成「尽量少用」,而是写成红线:一次都不行。 边界越绝对,越好守。

02替代品:四个接口 + 一个装配点

把 wx 挡在门外之后,core 需要的平台能力怎么办?答案是接口定义在 core 内, 实现在外,运行时注入。整个项目只有四个这样的接口:

接口能力wx 实现
StorageBackend持久化键值platform/wx-storage.ts
TcpSocketFactoryTCP 连接工厂platform/wx-tcp.ts
CloudCaller云函数调用platform/wx-cloud.ts
VoiceAdapter语音识别与播报platform/wx-voice.ts

app.ts 的 onLaunch 里调用一次 installPlatform() 完成装配——它是唯一同时依赖 core 和 platform 的装配点。 装配时还有一层小心思:适配器先做 API 存在性探测,缺失就保留 core 内置的 内存默认实现并记 warn。任何平台下应用都能启动, 降级是设计出来的,不是失败兜出来的。

这条纪律同时收敛了依赖方向。整个项目的依赖图严格单向: pages → session → ai/transport/device → dap → util, platform 只依赖 core 暴露的接口。没有一处反向依赖, 没有一处跨层穿透。

03靠人自觉守不住,所以做成机器校验

规则再硬,落在「团队自觉」上就一定会破。这个项目的解法是一个专用脚本:

npm run check:core-purity
扫描 core/** 中的:
      wx. / typeof wx / globalThis.wx / getApp( / 对 platform 与 app-container 的 import
    命中即失败,直接打印 文件:行号 与违规模式

    细节:会先剥离注释与字符串字面量
      → 注释里写「这里不要调 wx.showToast」不会误报

它和 typecheck、test 一起构成 npm run verify 提交前门禁。有个有趣的取舍: 项目没有 ESLint。理由是——唯一需要机器死守的风格类规则 就是这条 purity,专用脚本报错更精确(文件:行号 + 违规模式); 其余交给 tsc --strict 和 Prettier, 少一个会随版本漂移的工具链。工具是为目标服务的,不是越多越好。

连类型系统都参与了防守:tsconfig.test.json 只 include core/**,且把类型换成 ["jest", "node"]—— 单测环境里根本看不见任何 wx 类型。 如果 core 偷偷引了平台类型,测试编译直接报错。

04回报:数字和自由

这条红线的回报是可量化的:

当前基线
tsc --noEmit          零错误(strict 全开)
    core/**               48 个文件,零 wx 依赖
    单元测试              325 个用例,全绿
    语句覆盖率            91.7%(阈值:语句 70% / 分支 60% / 函数 65%)

但比数字更重要的是两笔看不见的账。第一笔是测试的成本曲线: core 里的协议编解码、文法引擎、状态机,测试写起来就是普通的 Node 代码, 没有 mock 的心智负担,覆盖率自然长到 90% 以上。 第二笔是迁移自由:云端解析通道(预留未启用)可以复用同一个 core, 因为它本来就不知道 wx 的存在。第一天定下的红线, 在需要跨宿主的那天变成了零成本。

可以复用的判断:可测试性不是「多写测试」写出来的, 是架构里那条「核心不碰宿主」的线画出来的。 线画得越早、越绝对,后面的测试和迁移越便宜。

05一条规则的三种 enforcement

复盘这条红线的落地手段,其实是三层保险:

  1. 文档:开发规范三条红线第一条,写明「连 typeof wx 都不允许」;
  2. 脚本:check-core-purity 并入 verify 门禁,机器报错精确到行;
  3. 类型:测试 tsconfig 不含 wx 类型,引了就编译失败。

三层各司其职:文档管共识,脚本管提交,类型管意外。 单独任何一层都可能漏,叠起来之后,这条红线在几个月的开发里 零违规——不是因为人都自觉,是因为违规的成本被压到了 「提交前就会红」的位置。

关于本文
整理自「一语控物」项目的架构纪律与测试基线 (docs/01 §2.3、docs/04 §3,以及 scripts/check-core-purity.mjs 的实施记录)。
2026.10.23 整理
写这篇时反复想起的一句话是「规则靠人自觉守不住」。这句判断的另一半是: 能被机器校验的规则,就应该被机器校验—— 专用脚本比通用 lint 工具更精确,把省下的工具链复杂度留给真正需要的地方。