SuperAPI AI 工具集

single-source-of-truth

编程与开发

查看项目

更新于 11-02 23:35

技能介绍

single-source-of-truth 是一份与编程语言无关的工程哲学文档,主题是消除“漂移”和“重复应用”类缺陷。它的基本判断是:这类 bug 形状相同,都是把某项正确性职责交给了人的记忆——“记得两边都更新”“记得它已经跑过”“记得调用检查”。人会遗忘,职责只会单调衰减。因此文档的每条规则都做同一件事:把职责从人身上转移到不会遗忘的机制上(编译器、类型、引擎、推导、测试),具体选择哪种机制因场景而异。

另一个观察角度是缩短“事实”与“使用处”之间的距离:每一份拷贝、每一次手工同步、每一个手动步骤、每一次运行时检查,都是两样东西可能产生分歧的地方。目标不是劝阻分歧,而是让分歧无法出现。

文档自述这些是“同一屋檐下的旧智慧”,其思想谱系包括丰田的防错(poka-yoke,把夹具做成零件无法装反)、成功之坑(让正确做法成为默认),以及“解析而非校验”(每次检查后若不把结果编码进类型,就是在要求未来的自己记住)。

八条规则及根因:

  1. 知识只有一个家(真正的 DRY,针对知识而非行数):两份拷贝只能靠纪律维持相等,分歧会静默存在直至爆发。
  2. 其余推导或生成:拷贝是拷贝时刻的冻结快照,源继续变化而拷贝无从知晓;推导每次从家重新计算,没有会过期的记忆。
  3. 声明目标状态而非步骤:命令式步骤暗含起始状态假设,从不同状态运行会破坏它;声明可被 diff、校验、可视化。
  4. 幂等,重跑即同一世界:现实只能保证至少一次投递,无法买到恰好一次投递,只能通过幂等买到恰好一次效果。
  5. 让非法状态无法表示:运行时检查依赖每个现在和未来的调用方都记得调用;类型不信任任何人,并可把保证前移到“根本写不出来”。
  6. 把事实与事物放在一起:按名字挂的旁表是手工维护的 JOIN,多出孤儿与缺失两种失败模式;字段放在结构体上则由编译器维护关联。
  7. 手工同步无法避免时,给漂移设闸:用标记块从一个来源生成另一个,测试在过期时失败,把“人记得重新同步”变成“构建变红”。
  8. 复用、小而稳定者应以包的形式拥有唯一的家——依赖而非拷贝,但必须先挣得:跨边界拷贝是最坏的漂移,因为想“记得更新另一份”的人根本不知道它存在;然而抽取也带来依赖边这一新缺口,只有小且稳定时才净收益为正,应等到第三次使用显露真实形状后再抽取,错误或过早的抽象代价高于它取代的重复(Rule of Three、AHA)。

文档还提供“坏味道→被寄托在人的职责→迁移方向”对照表,例如复制粘贴的常量、文档表格镜像代码、if alreadyDone 跳过、读改写计数器、旁挂 map、运行时“必须是其中之一”、注释“记得两边都更新”、同一逻辑拷入第三个仓库或团队等。并给出 Go builder DSL 示例:未导出字段、构造函数即名词、setter 返回 builder、解释器通过 GetX 读取,从声明生成契约文档并用漂移测试把关,判定集合作为类型的封闭契约在启动时检查一次。最后列举同一规则在其他领域的体现:Terraform/Kubernetes(规则3+4)、数据库迁移(4)、事件溯源(4)、Protobuf/OpenAPI 代码生成(2)、外键与 NOT NULL(5+6)、Rust 借用检查(5)、Stripe 幂等键(4)、电子表格公式与手工数字(2)。完整目录与跨域示例位于 EXAMPLES.md。

该资料属于方法论指导,不是可安装的软件;官方页面未提供收费、价格、支持平台或具体使用步骤等信息。