用ADR记录架构决策别再凭感觉做选择Awesome Architecture第08章实战指南【免费下载链接】awesome-architecture Architecture-first system design: 26 bilingual tutorials, 25 architecture templates, and 6 end-to-end cases covering distributed systems, AI-native systems, RAG, coding Agents, and production trade-offs.项目地址: https://gitcode.com/gh_mirrors/awesomearc/awesome-architecture在架构设计中最容易被遗忘的不是选了什么技术而是当初为什么这么选。ADRArchitecture Decision Record架构决策记录就是解决这个问题的轻量文档每个重要架构决策写一页纸把背景、决策、放弃的选项和取舍记下来随代码一起版本管理。本文基于开源项目 Awesome Architecture 的第 08 章 tutorial/08-架构决策记录与演进.md用实战视角带你掌握 ADR 的写法、原则和落地技巧。为什么凭感觉做选择最危险想象一个真实场景你接手一个三年前的系统发现订单数据被写进两个存储中间还有对账逻辑。第一反应是这不脱裤子放屁吗于是删掉一个、合并逻辑——三周后线上炸了。原因很简单当年之所以双写是因为监管要求订单流水必须落入不可篡改的存储而主库要支持高频改单两个诉求无法用一个存储同时满足。这个理由代码里一个字都没写拍板的人也早离职了。架构最致命的信息流失代码和图能说清系统是什么但几乎永远讲不清为什么这么选、当初放弃了什么。会议里讲过的原因会在三次会议、两次离职、一年时间之后蒸发得一干二净。等需要它的时候只剩下一个看起来莫名其妙的设计和一群不敢动它的人。ADR 是什么给架构决策建一本为什么的账ADR Architecture Decision Record架构决策记录。它是一份轻量文档精髓在于足够轻原则说明 一个决策一份通常一页纸几分钟能读完➕ 追加不修改决策变了就写新的旧的标记为被取代——保留历史而不是抹掉历史 和代码放在一起例如仓库里一个docs/adr/目录随代码一起被版本管理、被搜索、被 reviewADR 由 Michael Nygard 在 2011 年提出用一个个轻量小文件记录每个决策的背景、决定、状态和后果如今已是业界标准格式。六块模板一份可以直接抄走的 ADR 格式第 08 章给出了一个订单流水双写的完整 ADR 范例模板就六块记牢这六个标题就够了┌──────────────────────────────────────────────────────────┐ │ ADR-007:订单流水采用「主库 不可篡改日志」双写 │ ├──────────────────────────────────────────────────────────┤ │ 状态:已采纳草稿 / 已采纳 / 已废弃 / 被 ADR-015 取代 │ │ 日期:2026-05-23 决策者:架构组 合规 │ │ │ │ 背景:监管要求订单流水落入「写后不可改」的存储; │ │ 业务又要求订单可被高频修改。单一存储无法两全。 │ │ │ │ 决策:主库存可变订单状态;每次变更追加写入不可篡改日志; │ │ 以日志为准定期对账。 │ │ │ │ 其它选项:A. 软删除 → 否决(仍可被改,过不了审计) │ │ B. 只用不可篡改存储 → 否决(无法改单) │ │ C. 双写(本方案) → 采纳 │ │ │ │ 取舍: 同时满足合规与业务两个硬约束 │ │ − 需要对账逻辑兜底不一致(已知复杂度) │ └──────────────────────────────────────────────────────────┘字段写什么为什么不能省标题一句话说清这个决策是什么方便日后检索状态草稿 / 已采纳 / 已废弃 / 被某 ADR 取代让读者知道这条还算不算数背景当时面临什么问题、什么约束后人最缺的就是当时的处境决策我们最终决定怎么做代码里也能看到,但要留痕其它选项还想过哪些方案、为什么没选放弃了什么,是 ADR 独有的价值取舍与后果带来什么好处、什么代价、什么已知债务让后人清楚继承这份有意的取舍一句话立住原则好的文档不重复解释代码做了什么代码自己会说好的文档解释代码为什么这么做代码永远不会说。技术债也要记账有意识的债不是坏事技术债常被当成纯贬义词其实它借自金融含义为了现在更快地拿到价值有意识地选了个将来需要偿还的权宜方案。关键不是欠没欠而是知不知道、记没记、还还不还。处理技术债的纪律就三条✅有意识地借——明确这是权宜之计✅记下来——一笔技术债就是一条该写的 ADR背景说明为什么暂时这样做✅安排偿还时机——挂进 backlog定下当 X 发生时就还的触发条件而不是有空再说。何时该升级架构用尺子判断不拍脑袋凭代码看着丑或大厂都上微服务了升级架构是两种糟糕的依据。正确的做法是拿两把尺子量尺子一瓶颈——某个质量属性是不是已被架构真实卡住读库冒烟、发布越来越慢尺子二质量属性的变化——业务对要多好的要求是否上了台阶可用性 99% → 99.99%、用户量进下一个量级不是架构旧了就升级而是某个你真正在乎的质量属性被量出来的真实瓶颈卡住了才升级。而且每次升级本身就是一个该写 ADR 的重大决策。tutorial/演进触发信号.md 把这些判断落成可观测的量化信号速查表主库 CPU、P99 延迟、缓存命中率等没有信号就别动。实战练习把模板当 ADR 读Awesome Architecture 仓库里有个绝佳的练习场templates/ 下每个模板的第 8 节关键架构决策与权衡本质就是一组写好的 ADR。建议路径先读 tutorial/20-演进剧本MVP到规模化.md——同一个 AI 客服系统三段演进每段升级都落了一条 ADRADR-001 到 ADR-005背景栏全是量化信号没有一句感觉该升级了再挑 templates/ai-chat-product/README.md 里流式还是一次性返回这条决策按六块模板亲手补成一份完整 ADR最后回到 tutorial/README.md 的完整学习路径把 07 章设计与 08 章记录串成闭环。本章小结 最先丢失的永远是为什么——代码能自我证明是什么却永远不会说出当初放弃了什么 ADR 六块模板标题、状态、背景、决策、其它选项、取舍与后果一页纸即可 追加不修改保留历史本身就是宝贵信息 技术债的纪律有意识地借、记成 ADR、排期偿还 升级架构靠瓶颈 质量属性变化两把尺子每次升级本身就写一条 ADR。做出一个架构判断 → 把为什么记成 ADR → 业务长大、出现新瓶颈 → 重新判断……这个循环会让判断力复利增长。别再凭感觉做选择——把决策写下来才是架构师的分水岭。【免费下载链接】awesome-architecture Architecture-first system design: 26 bilingual tutorials, 25 architecture templates, and 6 end-to-end cases covering distributed systems, AI-native systems, RAG, coding Agents, and production trade-offs.项目地址: https://gitcode.com/gh_mirrors/awesomearc/awesome-architecture创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考