「一语控物」的全部可测试性,来自一条看起来很偏执的规则:
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 |
| TcpSocketFactory | TCP 连接工厂 | 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靠人自觉守不住,所以做成机器校验
规则再硬,落在「团队自觉」上就一定会破。这个项目的解法是一个专用脚本:
扫描 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
复盘这条红线的落地手段,其实是三层保险:
- 文档:开发规范三条红线第一条,写明「连 typeof wx 都不允许」;
- 脚本:check-core-purity 并入 verify 门禁,机器报错精确到行;
- 类型:测试 tsconfig 不含 wx 类型,引了就编译失败。
三层各司其职:文档管共识,脚本管提交,类型管意外。 单独任何一层都可能漏,叠起来之后,这条红线在几个月的开发里 零违规——不是因为人都自觉,是因为违规的成本被压到了 「提交前就会红」的位置。
- 关于本文
- 整理自「一语控物」项目的架构纪律与测试基线 (docs/01 §2.3、docs/04 §3,以及 scripts/check-core-purity.mjs 的实施记录)。
- 2026.10.23 整理
- 写这篇时反复想起的一句话是「规则靠人自觉守不住」。这句判断的另一半是: 能被机器校验的规则,就应该被机器校验—— 专用脚本比通用 lint 工具更精确,把省下的工具链复杂度留给真正需要的地方。
留言
正在载入留言…