/tags/adr/ Recent content in adr 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"。两者互补。 /posts/microservice-documentation-strategy-2026/ Fri, 10 Apr 2026 10:00:00 +0800 /posts/microservice-documentation-strategy-2026/ 在大规模微服务平台中，文档治理往往比架构设计本身更容易失控。Confluence、Notion 等中心化 wiki 工具在团队规模扩大后，很容易出现"文档漂移"（documentation drift）——文档与实际代码脱节，没人确定哪个版本更接近现状。 最近给自己的微服务项目搭文档站，选了 Docs-as-Code 这条路——文档和代码放同一个仓库，每个服务维护自己的 /docs/，最后用 Docusaurus 聚合成一个统一的门户。 这种模式和 Domain-aligned multi-repo 架构（每个 domain 有独立的 MS/BFF/consumer）比较契合：service owner 维护自己的 ADR 和设计文档，文档也更贴近代码；同时再通过 Docusaurus 提供统一入口。它和 Team Topologies 里 Stream-Aligned Team 的自治原则也比较一致。 这篇文章整理的是一套目前可落地的方案：组织结构、各服务 /docs/ 内容规范、Docusaurus 聚合机制、ADR 落地，以及我调研时看到的几种开源方案。 整体架构：三种仓库角色 在多仓库微服务平台中，文档体系涉及三种仓库角色： graph TD A["platform-architecture中央架构仓库"] -->|聚合| B["platform-docsDocusaurus 统一文档站"] C["MS repo"] -->|/docs/| B D["BFF repo"] -->|/docs/| B E["Consumer repo"] -->|/docs/| B 三种仓库的职责分工： 仓库类型 示例 文档职责 中央架构仓库 platform-architecture 全局架构概览、跨域决策、平台级 ADR、共享关注点（Kafka/Redis/Observability） 服务仓库 order-ms、user-bff 服务内部设计、服务级 ADR、API contract、Kafka 事件 schema、数据库 schema Docusaurus 文档站仓库 platform-docs 聚合所有来源的 Markdown，构建统一文档站（部署到 Vercel/Netlify） 这种分工的关键好处是：service owner 只需要维护自己 repo 的 /docs/，平台团队负责聚合和样式一致性。文档不一定会自动变好，但至少更不容易和代码长期脱节。