architecture-decision-record 实战:以"为项目选择 Java 编程语言"为例,写一份合格的架构决策记录(ADR)

原创2026-10-11 14:01:551,424 阅读

architecture-decision-record 实战:以"为项目选择 Java 编程语言"为例,写一份合格的架构决策记录(ADR)

架构决策记录(Architecture Decision Record,ADR)是一份把"重要架构决策及其背景、后果"固化下来的文档,是团队在软件规划与 IT 决策中最轻量、最实用的知识管理手段之一。本文以开源仓库 architecture-decision-record 中阿拉伯语示例 为项目选择 Java 编程语言(英文版见 Java programming language)为绝对主体,逐段拆解这份 ADR 的写法:它记录了"评估多种语言后选择 Java"这一决策的完整推理链条——背景、四大考量(安全、并发、大型代码库、通用性)、决策结果与四条后果。读完后,你将掌握一份可直接复制、可落地的 Java 技术选型 ADR 的完整结构,并了解如何结合仓库中的 ADR 概念定义、写作建议与 git 落地流程,把它应用到自己的项目中。

一、先理解:什么是 ADR,为什么"选 Java"值得写一份

在动手拆解这份 Java ADR 之前,先回到仓库的基础定义。什么是架构决策记录 给出了四个核心概念:

  • 架构决策记录(ADR):一份记录"重要架构决策及其背景与后果"的文档;
  • 架构决策(AD):一项应对重要需求(architecturally-significant requirement,ASR)的软件设计选择;
  • 架构决策日志(ADL):一个项目(或组织)创建并维护的全部 ADR 的集合;
  • 架构知识管理(AKM):上述内容共同归属的领域。

把"选 Java 作为项目编程语言"这样的决定写进 ADR,本质就是为未来开发者保留"为什么"——这正是仓库 写好 ADR 的建议 中强调的核心理念:一份 ADR 应该只围绕一个决策(Specific)、给出充分理由(Rationale)、标注时间(Timestamps)、保持不可变(Immutable,新信息追加而非篡改旧文)。本文的 Java 示例正是"一个 ADR 只讲一个决策"的典范:全文只回答一个问题——"项目用哪种编程语言"。

二、完整继承原文档:这份 Java ADR 的五个组成部分

原文档(阿拉伯语版,中文译版见 java编程语言)按以下顺序组织,这也是它最值得学习的地方——先陈述决策,再展开背景与理由,最后坦承后果:

1. 决策(Decision)

标题:为项目选择 Java 编程语言 决策:在评估了多种编程语言之后,我们决定为项目使用 Java。

开门见山,一句话给出结论。这符合 ADR"决策先行"的阅读体验:任何人打开文档,10 秒内就能知道团队选了 Java。

2. 背景(Background)

我们打算构建一个能在多种操作系统上运行的基于 Web 的应用。我们的项目需要一门语言,它能够提供强大的安全特性、处理并发、支持大型代码库,并且足够通用以满足我们未来的增长需求。在决定采用 Java 之前,我们评估了几种语言,权衡了它们的优势和局限。

背景部分交代了三条关键约束:应用形态(Web 应用)、运行环境(多操作系统,即跨平台)、增长预期(未来扩展)。这些约束直接决定了后面四个考量维度的选取——不是凭空罗列 Java 的优点,而是"需求驱动"地筛选评估标准。

3. 考量(Considerations)——四大评估维度

原文档给出了四个经过权衡的考量点,这是整份 ADR 的论证核心:

考量维度 原文要点(继承) 技术内涵解读(扩展)
安全性 Java 通过定义明确的安全策略和访问控制提供出色安全特性;包含字节码验证(bytecode verification),防止恶意软件在系统上运行 安全模型涵盖三层:语言层(无指针算术、自动边界检查)、字节码层(类加载时的字节码校验器验证类型安全)、运行时层(SecurityManager 与访问控制策略)。对跨平台 Web 应用而言,沙箱机制降低了运行不可信代码的风险
并发 Java 内置对多线程(multithreading)的支持,使应用能同时执行多项任务 java.lang.Thread、java.util.concurrent 并发工具包(Executor、ConcurrentHashMap、锁与原子类)是语言与 JDK 原生能力,无需引入第三方并发运行时;这使 Java 适合"多特性、多功能"的大型复杂应用
大型代码库 Java 支持面向对象编程;模块化特性与封装(encapsulation)、抽象(abstraction)模式简化开发 强类型 + 面向对象 + 包/模块机制(JPMS 模块系统)让大型团队可以按模块并行开发;编译期类型检查让大规模重构更可控
通用性 用途广泛,能使用大量库和框架,适合 Web 应用与企业级应用 从 Spring/Quarkus 等 Web 与微服务框架,到大数据(Hadoop/Spark)、中间件生态,覆盖面广,满足"未来增长需求"

4. 决策结果(Decision Outcome)

考虑到 Java 的安全特性、并发支持、处理大型代码库的能力和通用性,我们决定为项目使用 Java 编程语言。这一决策符合我们的项目需求,我们相信选择 Java 将确保项目的成功。

决策结果与开头的"决策"首尾呼应,并明确把结论重新绑定回项目需求——这是 ADR 论证闭环的关键:不是"Java 好所以我们选它",而是"Java 满足我们列出的需求,所以我们选它"。

5. 后果(Consequences)

原文档坦承了四条选择 Java 必须接受的代价:

  1. 需要有 Java 经验并能熟练使用的开发人员;
  2. 用该语言编写的任何代码都必须与 Java 虚拟机(JVM)兼容;
  3. 引入新特性、新功能或新框架可能带来一些挑战;
  4. 用 Java 开发大型复杂项目可能需要更多的时间和资源。

仓库 写好 ADR 的建议 明确指出,好的 Consequences 部分应说明决策带来的影响、后续行动,甚至"是否触发新的 ADR"。本例的后果 1 和 3 正是这种"引发后续决策"的典型:选 Java 之后,团队还需要接着决定"招聘/培训策略""采用哪些框架""构建工具链"等子问题。

三、仓库源码级佐证:Java 在"编程语言选型"专题中的定位

这份 Java ADR 并非孤立存在,仓库 示例目录 将编程语言选型组织为一个专题族:既有按单语言拆分的 Go、Rust、Java、Python 等"单语言 ADR",也有综合性的 编程语言选择(采用 Tyree & Akerman 风格,列出 Issue / Decision / Status / Positions / Argument 等小节)。这种"总-分"结构本身就是一个很好的组织范式:一个宏观的语言选型 ADR 可以先定大方向,再为每个具体语言选择派生独立的子 ADR。

在综合版 编程语言选择 的 Argument 中,Java 被这样评估:

Java:优秀的运行时(excellent runtime);优秀的生态(excellent ecosystem);开发体验欠佳(sub-par developer experience)。

这句话与本文 Java ADR 的"后果"形成了有趣的互证:两者都承认 Java 的运行时与生态是强项,同时都暗示了"开发体验/上手门槛"是代价。也就是说,仓库内不同 ADR 对同一技术的评价是自洽的——阅读时可以交叉对照:当你的团队也要写语言选型 ADR 时,既可以用本文这种"单语言决策记录"格式,也可以用综合版把 Java、Go、Rust 放在同一张 Positions 表里横向比较,并像综合版那样给每个候选语言一句话结论(例如它对 Clojure、Elixir、Kotlin、TypeScript 等的点评),再把最终选择单独落成一份本文这样的 ADR。

四、对照模板:这份 Java ADR 与主流 ADR 模板的关系

如果你想把它扩展为更正式的记录,仓库收录了两套主流模板,可直接对照:

  • Michael Nygard 模板(decision-record-template-by-michael-nygard):四段式 Status → Context → Decision → Consequences。本文 Java ADR 的"背景/考量"对应 Context,"决策/决策结果"对应 Decision,"后果"对应 Consequences;唯一欠缺的是 Status 段——建议在实际使用时补上 Status: Accepted(或 proposed / rejected / superseded 等)。
  • Jeff Tyree & Art Akerman 模板(decision-record-template-by-jeff-tyree-and-art-akerman):更细化的 14 个字段,包括 Issue、Decision、Status、Group、Assumptions、Constraints、Positions、Argument、Implications、Related decisions、Related requirements、Related artifacts、Related principles、Notes。综合版 编程语言选择 正是这一模板的实践——它明确列出了被评估的 16 种语言(Positions)和各语言的论证(Argument),如果把它与本文 Java ADR 合并,就能得到一份"备选充分、结论明确、后果透明"的完整决策档案。

把本文 ADR 映射到 Tyree & Akerman 模板时,可以这样补全:Assumptions(团队能招聘到 Java 开发者、项目需要跨平台 JVM 运行时)、Constraints(代码必须兼容 JVM、需支持主流云平台函数服务等)、Related decisions(框架选型、构建工具选型、IDE 选型)。这些字段的补全正是 写好 ADR 的建议 中"Context 要说明组织情况与团队技能构成"的落地。

五、落地到你的项目:用 git 管理这份 Java ADR

仓库根目录 README 的 "How to start using ADRs with git" 给出了把 ADR 纳入版本控制的标准流程(英文原文):

# 1. 为 ADR 文件创建目录
$ mkdir adr

# 2. 为每条 ADR 创建一个文本文件,例如 choose-java.md
$ vi choose-java.md

# 3. 写入任意想记录的内容(可参考本仓库的模板与示例)

# 4. 提交到 git 仓库
$ git add adr/choose-java.md
$ git commit -m "add ADR: choose Java as programming language"

文件命名方面,仓库推荐的约定(见 文件命名规范相关文档 及 index.md):使用现在时祈使短语(如 choose-java.md、format-timestamps.md),全小写 + 短横线,扩展名为 .md。将本文 ADR 套用此约定,文件名就是 adr/choose-java.md——命名即承诺,未来任何人打开目录都能一眼看出"这是关于选 Java 的决策"。

关于文档的生命周期,仓库建议保持"活文档"理念:决策后如有新信息(如新框架出现、招聘结果、实际运行反馈),应在原 ADR 中追加带日期的新条目而非改写旧内容(写好 ADR 的建议),并且建议团队在决策约一个月后做一次复盘,把 ADR 中的预测与实际情况对照。对本文 Java ADR 而言,"后果 3(引入新框架有难度)"和"后果 4(大型项目耗时耗资源)"就是非常适合在复盘时验证的两条预测。

六、总结:这份 Java ADR 教给我们的四个写作要点

回到本文主体 为项目选择 Java 编程语言,可以提炼出四条可复用的 ADR 写作经验:

  1. 决策先行,论证闭环:开头一句话给结论,背景给出约束,考量用"需求→维度"的方式组织,结尾的决策结果回扣背景——四个部分环环相扣;
  2. 一个 ADR 只讲一个决策:全文只回答"选哪种编程语言",不混入框架选型、部署方案等其他决策;那些话题留给后续独立的 ADR;
  3. 考量要可辩护、可对照:安全、并发、大型代码库、通用性四个维度均源于背景中的项目需求,配合仓库综合版 编程语言选择 中的候选语言对比,能让"为什么不是 Go/Rust/Python"这个问题有据可答;
  4. 后果要诚实:人才门槛、JVM 兼容约束、框架引入难度、时间资源成本四条后果,与 综合版 ADR 对 Java"运行时与生态优秀、开发体验欠佳"的评价互相印证——不回避代价的 ADR 才值得被团队信任。

如果你正面临类似的技术选型,可以把本文的五个部分当作模板直接套用;若需要更严谨的备选方案对比,则参考 Tyree & Akerman 模板的 Positions/Argument 结构;最后,用 mkdir adr && vi choose-java.md 把它提交进版本库,让"为什么选 Java"成为项目长期资产的一部分。

登录后查看全文
architecture-decision-record