Bliki: Architecture Decision Record
很多软件团队都遇到过这样的场景:一个新成员加入项目,看着代码库里的某个关键设计,问“为什么这里要用消息队列而不是直接调用?”没人能立刻说清楚,因为当初做决定的人可能已经走了,或者大家早就忘了讨论的细节。更糟的是,几个月后,同样的争论又重来一遍,因为没有人记录下当初为什么选A而不是B。Martin Fowler 在 bliki 上介绍的架构决策记录(Architecture Decision Record,简称 ADR)就是为解决这个问题而生的。它不是那种冗长的设计文档,而是一种轻量级的记录方式,专门用来捕捉每一个重要的架构决策及其背后的理由。一个典型的 ADR 只有几个部分:标题、状态(比如“已提议”“已接受”“已废弃”)、上下文(Context)、决策(Decision)和后果(Consequences)。上下文部分描述当时面临的问题、约束条件和可选方案;决策部分明确写下了最终选择以及为什么选它;后果部分则诚实地评估这个决策带来的正面和负面影响。比如,一个团队决定用微服务架构,他们可能在 ADR 里写下:上下文是单体应用已经难以维护,团队规模扩大到 20 人,部署频率需要从每月一次提高到每周多次;决策是拆分为六个微服务,每个服务独立部署,理由是降低耦合、提升团队自治;后果则是增加了网络通信的复杂性、需要引入服务发现和分布式追踪。这个记录本身就是一个活文档,随着项目演进,状态可以变为“已废弃”,并引用新的 ADR 说明为什么放弃。Fowler 强调,ADR 的价值不在于记录了多少技术细节,而在于保留了决策的“为什么”。当新成员加入,或者老成员遗忘时,他们可以快速理解设计的初衷,避免重复踩坑。更重要的是,ADR 让架构演进变得可追溯,你可以像读故事一样,看到团队是如何一步步做出权衡的。比如,为什么后来决定把某个服务合并回去?因为流量没预期大,拆分带来的运维成本超过了收益。这个理由记录在 ADR 里,就让后来的决策有了依据。如果你在团队里推行 ADR,可以从一个简单的模板开始,放在代码仓库的 docs/adr 目录下,每次做出重要架构决策时就写一篇。不用很长,三四百字就够了。关键是养成习惯,就像写代码注释一样自然。久而久之,它就会成为团队最宝贵的知识资产之一。