guarding-architecture

架构守护

必备背景知识： principal-engineering 技能。

概述

结构不变量是承重契约：违反其中一条，会引发一类 Bug，而非单个缺陷。重要的不变量必须有名称、书面说明其理由，并配有机械化守护；没有守护的不变量只是愿望。

模式

1. 为不变量命名。 以编号标记，便于引用（“法则 3”）；每条都包含一项陈述（与技术无关，旨在超越任何框架而长期适用）、一项理由和若干影响。理由应具体描述故障经过：违反不变量时会出现哪类 Bug，并从一次事故出发叙述，而非抽象论述。
2. 将稳定部分与易变部分分开。 原则文档很少变动，也不提及任何类；其当前实现（规范所有者、守护机制、参考设计）则放在配套文档中，随代码变化。两者不一致时，以不变量为准，并修正实现文档。
3. 以机械方式强制执行。 每条可强制执行的不变量都要有架构测试，且测试失败时构建也应失败：依赖方向、包边界、分层规则、禁止导入等。无法通过构建强制执行的内容，应成为一项有名称且引用不变量的评审检查项。
4. 违反不变量意味着重新设计，而非找理由辩解。 违反已命名不变量的设计，从根本上就是错误的：应重新设计，而不是将例外辩解进规范。为了迎合不合规代码而削弱契约，是明令禁止的做法；应记录违规情况并修复代码（这与技术写作者插件应用于规范性文档的规则相同）。
5. 规范应展示合规性。 涉及受守护范围的设计，应指出涉及哪些不变量，并逐条说明如何遵守；评审者依据已命名的不变量核查声明，而不是争论个人偏好。
6. 例外就是修订案。 真正的例外必须提出修订案，指出所放宽的不变量及放宽范围；默许的例外会让不变量沦为建议。这是唯一合法的例外形式，而第 4 点禁止其他所有形式；负责人无法联系并不构成例外，因此变更必须等待或以合规方式落地。真正临时的例外应是注明日期的豁免，包含到期条件并经负责人签字确认，记录在易变的实现文档中，而不是为了满足当前情况而修订稳定的不变量。
7. 未作说明的守护排除项，就是隐藏在构建之外的违规。 发现此类排除项的人应告知该不变量的负责人。排除项绝不能成为下一个排除项的先例；以“别人也这么做”为由扩展排除列表，等于认可侵蚀，而非遵循模式。

常见不变量类别

大多数系统都值得守护的示例，而非强制要求：

• 每个关注点只有一个规范所有者（参见 keeping-one-source-of-truth）。
• 依赖方向：领域层绝不导入交付机制。
• 关键路径隔离：热路径上不得有 I/O，也不得依赖缓慢或可选的依赖项。
• 默认拒绝边界：无法评估的关卡必须拒绝（参见 handling-failures）。
• 迁移不可变性（参见 principal-engineering)。

常见错误

• 原则文档里塞满类名：这只是披着错误标题的实现文档；应将两者拆开。
• 「暂且」添加导入。边界会被一次次方便的导入侵蚀；设置防护机制，正是因为每次违规在局部看来都合情合理。
• 在评审中声称某项不变量存在，却未将其纳入构建：只有合适的评审人员在场时才能执行。
• 以符合要求的成本为由为违规辩解。成本论据或许成立，但正确做法是由负责人决定修改不变量，并记录下来（如果已安装 recording-decisions，则通过它记录），而不是在某个规范中悄悄开例外。
• 将原则写成品味偏好（「倾向于使用小模块」），而非契约（「模块 X 绝不导入模块 Y」）。契约可以让构建失败；品味只能让人心情不好。