keeping-one-source-of-truth

保持唯一事实来源

必需背景：principal-engineering 技能。

概述

系统中的每项事实都只存在于一个地方，系统的其他部分都从那里读取。这一原则优先于便利性。

原则

1. **添加数据前，先找出已有的归属方。**扩展已有归属方；不要另起炉灶。
2. **推导，而非存储。**如果平台或现有来源能在读取时给出答案，就从那里读取；不要把答案复制到第二个来源，否则副本可能过时。
3. **顺手整合发现的重复项。**如果你接触的代码硬编码了文件中已有的信息（或反过来），就把两者整合起来，而不是留下第三种变体。
4. 缺少条目时必须明确报错（参见 handling-failures）：只有在缺少条目会报错，而不是静默使用默认值时，唯一来源才具有权威性。
5. **标明内容是生成的还是手动编辑的，绝不编辑生成内容。**每项产物都要注明这一点。
6. **词汇必须有类型，而不是随意使用字符串。**代码分支所依据的标识符、种类、状态和名称，都应是常量、枚举、密封类型或注册表条目；同一个自由字符串拼写两次，就形成了两个事实来源，中间还可能出现拼写错误。
7. **两个来源不一致时，要明确指出。**揭示矛盾是修复的第一步。彻底修复要确定哪个值实际生效，将其归并为唯一来源，并删除另一个。绝不能静默采用其中任意一个；那会把矛盾掩盖起来，最终只留下你恰好先读取的那个答案。在已声明的关键路径上，出现实际的不一致时，应直接通知负责人，而不能只创建跟踪事项；无人查看的工单无法揭示问题。

边界

• 缓存和读取模型属于合理的派生副本，前提是它们由自动流程生成，且其过时程度有界并可观测。此规则禁止的是需要人工保持同步的副本。
• 测试固件可以有意冻结现实的副本；“固件”这个词就是说明。
• 文档也遵循同一规则（索引负责引导，不负责决策）；安装了技术写作者插件的项目，可通过该插件的 technical-writing 技能处理这部分。

常见错误

• “暂时”复制阈值、URL 或映射。“临时”副本的存续时间，往往和它上方的 TODO 一样长。
• 在 thing 旁边创建 thing-v2，而不是直接修改原有内容。
• 在代码中设置一个默认值，覆盖配置文件中的值。有人修改配置却发现毫无变化，原因就在这里。
• 两个服务中有两个枚举，拼写着相同的状态。其中一个新增状态的那一天，它们之间的边界就会变成一个静默过滤器。