这份附录怎么用
附录 A 不是词典，而是评审时的共同语言。当会议上有人说「这个端不一致」「这个组件该共享」「这次迁移可以结束了」，速查表用来说明：他说的「不一致」是哪一级，「共享」受哪条边界约束，「结束」需要满足哪些条件。
每条术语给四样东西：定义、判断条件、常见误用、对应章节。判断条件尽量写成可观察的事实，而不是形容词。
一、承诺（promise）
定义：一个端对另一个端必须保持的行为约定。
三级：
| 等级 | 判断条件 | 典型对象 | 验收 |
|---|---|---|---|
identical | 同一输入得到同一结果、同一文案、同一顺序 | 金额、订单状态、支付结果、退款进度 | 逐字段跨端比对 |
equivalent | 关键字段一致，呈现可以不同 | 列表排序、页面结构、通知文案 | 场景断言关键字段 |
allowed-diff | 端能力不同，允许缺失或替代 | 桌面无推送、小程序分享形态 | 明示降级路径 |
判断条件：如果一处差异会导致资金、履约或用户权益判断不同，它必须是 identical；如果只影响观感与路径，最多 equivalent。
常见误用：
- 把布局也定成
identical，导致所有端向最弱端对齐。 - 只写等级不写验收方式，等级变成口号。
- 用「差不多」代替
equivalent，联调时才发现关键字段不同。
对应章节：1.1、1.2、9.1、10.1。
二、边界（boundary）
定义：代码、数据与责任的分界。卷四用四层依赖表达代码边界。
| 层 | 职责 | 允许依赖 |
|---|---|---|
core | 纯判断、领域规则 | 仅 core |
protocol | 接口、契约、序列化 | core、protocol |
adapter | 平台实现、网络、存储 | 前三层 |
ui | 视图与交互 | 任意层 |
判断条件：如果一条依赖从低层指向高层，或者图中存在环，边界已被破坏。
常见误用：
- 把「工具函数」放进
core，实际依赖了浏览器 API。 protocol直接引用ui的类型，形成隐式耦合。- 用目录结构假装分层，实际靠 import 路径绕开。
对应章节：1.2、2.2、6.1、11.2。
三、能力（capability）
定义：某个端是否具备某项原生能力。
| 状态 | 含义 | 处理 |
|---|---|---|
native | 原生支持 | 直接使用 |
polyfill | 有替代实现 | 优先替代 |
absent | 不支持 | 按需求等级降级或阻塞 |
需求等级：required 缺失时阻塞；optional 缺失时降级。
判断条件：能力表未声明某项时，按 absent 处理，不按「大概率支持」处理。
常见误用：
- 默认值取「支持」，问题推迟到线上。
- 把降级做成「按钮置灰」，用户点进去才知道不可用。
- 只在启动时探测一次，权限变化后不刷新。
对应章节：1.3、3.2、9.3、10.2。
四、性能预算（budget）
定义：按端、按阶段分配的耗时与资源上限。
| 维度 | 典型阶段 | 判定 |
|---|---|---|
| 启动 | 冷启动、热启动 | 超过预算即失败 |
| 首屏 | 请求、解析、渲染 | 分阶段归因 |
| 交互 | 输入到响应 | 超过即标记 |
| 内存 | 峰值、常驻 | 超限告警 |
判断条件：预算必须分端，且每一阶段有独立阈值；只有总预算时无法归因。
常见误用：
- 五个端共用一个预算，弱端永远超标、强端永远宽松。
- 只测平均值，不看尾部。
- 优化后不更新基线，回归无法发现。
对应章节：4.1、4.2、4.3。
五、稳定性（stability）
定义：故障发生时，系统把影响限制在可接受范围内的能力。
| 概念 | 定义 | 判断 |
|---|---|---|
| 故障域 | 一组会一起失败的组件 | 单点越少越好 |
| 爆炸半径 | 故障影响的功能/用户比例 | 需可估算 |
| 降级 | 用较弱能力维持主流程 | 必须有可用路径 |
| 开关 | 运行时改变行为的控制点 | 必须有 owner 与过期时间 |
| 演练 | 主动注入故障验证机制 | 需有恢复断言 |
判断条件：如果无法回答「这个依赖挂了会影响哪些功能」，故障域没有被定义。
常见误用：
- 开关只增不减，半年后没人知道哪个还能关。
- 降级路径从未被测试，真故障时同样不可用。
- 演练只看「有没有报错」，不看恢复时间与数据一致性。
对应章节：5.1、5.2、5.3。
六、交付（delivery）
定义：从代码到可发布产物的过程，包括包边界、缓存与流水线。
| 概念 | 判断条件 |
|---|---|
| 包边界 | 跨包引用必须显式声明，禁止隐式深层导入 |
| 产物缓存 | 缓存键包含源码、依赖、构建配置的哈希 |
| 灰度 | 每批有明确比例、观察窗口与停止条件 |
| 回滚 | 回滚版本可用，且数据兼容 |
常见误用：
- 缓存键只用文件路径，配置变了仍命中旧产物。
- 灰度只看崩溃率，不看核心功能成功率。
- 回滚脚本存在但从未演练。
对应章节：6.1、6.2、6.3、12.3。
七、可观测性（observability）
定义：用最少的字段回答「发生了什么、影响谁、为什么」。
| 概念 | 判断条件 |
|---|---|
| 最小契约 | 每条事件含时间、端、版本、功能、结果、耗时、trace |
| 采样 | 按事件等级分层，错误与阻塞全量 |
| 脱敏 | PII 字段在采集端移除，不依赖下游 |
| 告警闭环 | 每条告警有 owner、runbook、关闭条件 |
常见误用：
- 字段很多但没有统一命名，无法聚合。
- 采样把错误也采掉，线上问题查不到。
- 告警只发群，没有 owner，最后没人处理。
对应章节：7.1、7.2、7.3。
八、安全与隐私（security & privacy）
定义：数据离开设备前的采集、使用与授权边界。
| 概念 | 判断条件 |
|---|---|
| 数据分级 | 每类数据有级别与允许用途 |
| 最小权限 | 每个 SDK/模块只拿完成功能所需的数据 |
| 同意 | 采集前有可追溯的同意记录 |
| SDK 治理 | 有清单、版本、权限、退出机制 |
常见误用：
- 分级只写在文档里，代码中没有对应检查。
- 第三方 SDK 随业务接入，无人汇总权限。
- 同意状态只存本地，卸载重装后丢失。
对应章节：8.1、8.2、8.3。
九、国际化（i18n）
定义：同一功能在不同语言、时区、货币、区域下保持等价。
| 概念 | 判断条件 |
|---|---|
| 文案 | 无硬编码，支持复数与性别 |
| 时区 | 存储 UTC，展示按用户区域 |
| 货币 | 整数最小单位，按区域规则舍入 |
| RTL | 布局镜像，图标与方向语义正确 |
| 区域能力 | 支付、物流、地图等按区域降级 |
常见误用：
- 用字符串拼接句子，翻译后语序错乱。
- 用浮点数存货币，舍入误差累积。
- RTL 只镜像容器，不镜像图标与键盘方向。
对应章节：9.1、9.2、9.3。
十、无障碍（a11y）
定义：不同能力用户都能完成同一任务。
| 概念 | 判断条件 |
|---|---|
| 语义 | 控件有角色、名称、状态 |
| 焦点 | 顺序与视觉顺序一致，焦点可见 |
| 读屏 | 状态变化有播报，不依赖颜色 |
| 偏好 | 支持减少动效、放大字体、高对比 |
| 验收 | 有自动化检查与人工走查 |
常见误用：
- 用
div加点击事件代替按钮。 - 焦点顺序按 DOM 顺序而非视觉顺序。
- 只做静态检查，不测读屏实际播报。
对应章节：10.1、10.2、10.3。
十一、治理（governance）
定义：谁决定、谁检查、谁承担后果。
| 概念 | 判断条件 |
|---|---|
| ADR | 记录背景、选项、决定、后果与复审时间 |
| 所有权 | 每个包/模块有 owner 与备份 owner |
| 技术债 | 有台账、分级、偿还节奏 |
| 规则 | 少量硬规则，自动化检查，失败即阻断 |
常见误用：
- ADR 只写「决定了什么」，不写放弃了什么。
- 所有权挂在团队名下，实际无人负责。
- 技术债台账只增不减，没有偿还计划。
对应章节：11.1、11.2、11.3。
十二、迁移（migration）
定义：从旧架构到新架构的受控替换。
| 概念 | 判断条件 |
|---|---|
| 绞杀者 | 新路径按流量比例接管，旧路径保留 |
| 双写 | 两个写入路径都可回滚，有一致性校验 |
| 兼容窗口 | 明确起止时间与退出条件 |
| 退出 | 旧路径无流量、无回滚需求、数据已校验 |
常见误用：
- 迁移没有退出条件，旧代码永久保留。
- 双写只写不校验，分叉数月后才发现。
- 宣布完成后立即删除旧路径，没有观察期。
对应章节：12.1、12.2、12.3。
一页纸判据
把上面十二组压缩成十二个问题，评审时逐条问：
- 这一处差异属于哪一级承诺？验收方式是什么？
- 这条依赖是否越层？图里有没有环？
- 这个能力未声明时按什么处理？
- 这个阶段的预算阈值是多少？超了谁负责？
- 这个依赖挂了影响哪些功能？降级路径测过吗？
- 这个包允许被谁引用？缓存键包含什么？
- 这条事件的最小字段齐吗？错误会被采样掉吗？
- 这类数据属于哪一级？谁授权采集？
- 这个格式在目标区域正确吗？RTL 下会怎样？
- 这个控件读屏会读出什么？焦点顺序对吗？
- 这个决定记录在哪？owner 是谁？
- 这次迁移什么时候算结束？旧路径何时删除？
十二个问题答不上来的部分，就是下一轮治理的输入。
术语对照
| 中文 | 英文 | 本文用法 |
|---|---|---|
| 端 | endpoint | 独立发版的交付形态 |
| 承诺 | promise | 跨端行为约定 |
| 边界 | boundary | 代码/数据/责任分界 |
| 能力 | capability | 端是否具备某项原生能力 |
| 策略 | strategy | 能力不足时的处理方式 |
| 故障域 | fault domain | 会一起失败的组件集合 |
| 爆炸半径 | blast radius | 故障影响范围 |
| 绞杀者 | strangler | 渐进替换旧路径 |
| 兼容窗口 | compatibility window | 新旧并存的受控时段 |
同一个词在不同团队可能有不同含义，评审前先对齐这张表，比争论定义更省时间。
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。