Software Architect · 模块 18
架构文档不是给档案馆的。它存在,是为了让新人能理解系统,让老人能记起当初为什么这么决定。
ADR · C4 · runbook · decision record · context
你记录的不止是结果——你记录的是 context:为什么选这个、否决了哪些备选,以及什么时候该回头重新审视这个决策。
ADR 把一个决策钉在时间里
施工现场的一张照片不能取代图纸,但它确实能帮你弄明白:这堵墙当初为什么砌在了这里。
一份 Architecture Decision Record 通常装着 context、decision、consequences、alternatives 和 status。它不必很长。它的职责是保存当时的推理。
一年之后,团队可能想不起来当初为什么选 Postgres、为什么放弃了 Kafka、为什么保留了一个同步 API。ADR 让你不必在没有原始 context 的情况下,把同一场争论重新打一遍。
一张图必须回答一个问题
地铁图不画下水道——乘客不需要。一张好图会挑选它的细节层级。
C4 model 作为一组层级很有用:context、container、component、code。stakeholder 需要的是 context。团队需要的是 container 和重要的 component。事故响应需要的是 runtime 视图和依赖关系。
一张画着"整个系统"的巨型大图通常没什么用:它要么过期,要么没法读。
好的文档住在改动旁边,而且有 owner。
例子:为队列选型写一份 ADR
在会议纪要里,决定本身很重要——但"为什么其他选项不合适"同样重要。
这份 ADR 记下:我们需要投递领域 event,要支持 replay、按 key 的 ordering,以及持久化存储。我们考虑过 RabbitMQ、managed Kafka 和数据库 outbox。我们为了吞吐量选了 managed Kafka——并接受了它的运维成本和 schema governance 负担。
这样一份文档,能帮未来的团队看清:这个决策什么时候依然成立,什么时候 context 已经变了。
反例:把 Confluence 当成坟场
一仓库的旧说明书看着挺唬人——直到你意识到,没人知道哪一份是当前有效的。
文档和代码住在两处,没有 owner,PR 上不更新,还塞满了三年前的截图。新人很快就学会无视它。
更少的文档、配上清晰的生命周期,效果更好:owner、last-reviewed 日期、从代码链接过去、架构变更时必须更新。
- 哪些决策值得一份 ADR? - 新人第一天需要的是哪张图? - on-call 需要哪些 runbook? - 团队怎么知道一份 文档已经过期了?