/tags/service-catalog/ Recent content in service-catalog on Hugo -- gohugo.io en Sun, 26 Apr 2026 01:00:00 +0800 /posts/adr-and-service-catalog-2026/ Sun, 26 Apr 2026 01:00:00 +0800 /posts/adr-and-service-catalog-2026/ 📦 本文基于的完整项目源码：meirongdev/shop 服务数到 5 个时，靠口口相传和 README 还能维护。到 16 个时，新人入职第二周问的"order-service 发什么事件、谁在消费、出问题找谁"已经没有一个人能答全。这是我在 shop-platform 遇到的一个规模拐点。本文记录两份成本相对较低、回报也比较稳定的治理文档：ADR（架构决策记录）和 Service Catalog（服务目录）。至少在我这套项目里，它们值得投入。 一、ADR 是什么、为什么需要 Q：架构文档不是已经在 README 和 design doc 里了吗？ 它们描述当前的形态，不描述为什么形成这种形态。 举例：项目里有一条规则"@HttpExchange 客户端必须放在调用方模块、不能放共享模块"。架构文档会写"这是约定"。但答不出来—— 为什么？业界普遍是"共享 client SDK"模式。 之前是不是试过共享模式？为什么放弃？ 改回共享模式会发生什么？ 这些问题的答案是决策的上下文，半年后所有当事人都会忘。新人提 PR 想"重构"成共享模式时，没人能说出具体反对理由——只能凭"这是规矩"挡回去。一年后规矩本身被推翻，团队又走了一遍同样的路。 ADR 把这个上下文以最小代价封进版本历史。一份 200 字的 markdown 就能保住"为什么"的链路。 Q：ADR 跟 design doc 的区别？ 维度 ADR Design Doc 体量 一页（200-500 字） 几页到几十页 时机 决策点 实现前 内容 选了什么、放弃了什么、为什么 怎么实现 寿命 永久（即使 superseded 也保留） 实现完通常归档 可写时机 当时写或事后追溯都行 必须事前 design doc 回答"how"，ADR 回答"why"。两者互补。