用 ADR 记录编程语言选型:以 architecture-decision-record 仓库的 Rust 采用决策(AR-001)为例

原创2026-10-11 13:40:041,691 阅读

用 ADR 记录编程语言选型:以 architecture-decision-record 仓库的 Rust 采用决策(AR-001)为例

本文以开源仓库 architecture-decision-record 中收录的决策记录 programmeringssproget-rust(采用 Rust 编程语言,编号 AR-001)为主体,完整拆解一条 ADR 从「问题陈述」到「后果」的写作脉络,并结合仓库内的多语言镜像、MADR 模板与写作规范,说明如何用 ADR 沉淀一次真实的技术选型决策,让团队与未来的开发者都能读懂背后的「为什么」。

这条 ADR 记录了什么

在仓库的丹麦语目录 locales/da-001/eksempler/programmeringssproget-rust/README.md 中,保存了一条完整的架构决策记录(Architecture Decision Record,ADR)。它对应中文镜像 locales/zh-001/示例/rust编程语言/README.md 与英文源文档 locales/en-001/examples/rust-programming-language/README.md。

这是一条围绕「引入 Rust 作为新编程语言」的决策记录,全文采用经典的 ADR 章节骨架,依次包含:

  • 元信息:决策编号、决策标题、日期、状态;
  • 问题陈述(Problem Statement):为什么要做这个决定;
  • 考量(Considerations):评估时的关注维度;
  • 约束(Constraints):必须满足的边界条件;
  • 实施(Implementation):落地的行动步骤;
  • 理由(Rationale):选择 Rust 的技术依据;
  • 后果(Consequences):决策带来的正反两方面影响。

整条记录约 60 行 Markdown,却完整覆盖了「背景—权衡—行动—依据—影响」的决策闭环,是学习如何写 ADR 的典型范本。

元信息:让一条记录可被追溯

ADR 的开头应当给出可索引的元数据。AR-001 的做法是:

  • 决策编号:AR-001
  • 决策标题:采用 Rust 编程语言(Adoption of Rust programming language)
  • 日期:2021 年 12 月 1 日
  • 状态:已接受(Accepted)

编号(AR-001)让决策可以在架构决策日志(ADL)中被唯一引用;日期用于标识决策作出或最后更新的时间;状态则表明这条决策当前的生命周期位置。仓库的写作规范 skills/architecture-decision-record-skill/reference/writing-guide.md 建议状态取值包括 proposed | accepted | rejected | deprecated | superseded by <link>,并且强调「对可能随时间变化的内容打上时间戳」——成本、工期、规模数字都可能在数月后失效,时间戳正是为了防止这类信息腐烂。

问题陈述:从痛点出发,而不是从结论出发

AR-001 的问题陈述非常典型:

随着我们持续开发软件应用,缓解潜在安全漏洞、防止运行时错误变得越来越困难。在使用 C 和 C++ 等现有语言时,我们仍不断遇到缓冲区溢出、内存泄漏、未定义行为导致应用崩溃等问题。我们需要一门能提供内存安全保证、又足够高效以支撑性能关键型应用的语言。

这段陈述的价值在于:它给出了决策的驱动力(安全漏洞与运行时错误),点名了现状缺陷(C/C++ 的内存安全问题),并明确了期望目标(内存安全 + 高性能)。一个好的 ADR 问题段应当做到「未来的开发者不用在场,也能知道当时为什么要做这个决定」,这正是仓库 README.md 中「让未来开发者理解 why」的核心理念。

考量:把评估维度写清楚

在正式下结论之前,AR-001 列出了六项考量维度:

  1. 内存安全与安全性(Memory safety and security)
  2. 性能与效率(Performance and efficiency)
  3. 社区支持与采用情况(Community support and adoption)
  4. 学习曲线(Learning curve)
  5. 工具与生态系统(Tools and ecosystem)
  6. 与现有软件系统的兼容性(Compatibility with existing software systems)

这六项维度不是随意罗列,而是对问题陈述的呼应:内存安全对应痛点,性能对应「性能关键型应用」的诉求,社区、工具、学习曲线与兼容性则覆盖了「引入新语言」这一行为本身的风险面。写 ADR 时,考量的价值不在于「列得全」,而在于每一条都能在后面「理由」和「后果」部分被回应。

仓库中另一条更宏观的决策记录 locales/da-001/eksempler/programmeringssprog/README.md(中文镜像 locales/zh-001/示例/编程语言/README.md)展示了另一种做法:它直接枚举 C、C++、Clojure、Elixir、Erlang、Elm、Flow、Go、Haskell、Java、JavaScript、Kotlin、Python、Ruby、Rust、TypeScript 共 16 门候选语言,并逐条给出「接受/否决」的理由摘要,例如:

  • C:因安全性低被否决,Rust 几乎在所有方面都能做得更好;
  • C++:因其混乱被否决,Rust 几乎在所有方面都能做得更好;
  • Rust:最好的新语言,强调零抽象代价与并发,但生态系统相对较小,且对某些编译器加速存在刻意限制(如直接内存访问需显式标记为 unsafe)。

把「考量维度」和「候选方案对比」结合起来,正是决策记录应有的论证深度。

约束:边界条件决定方案可行域

AR-001 明确写下了约束:

引入新语言需要重新培训开发人员,需要投入时间与资源;将语言整合进现有开发工作流可能具有挑战;必须确保与现有系统兼容,避免破坏性变更,以保持连续性。

约束的价值在于防止「理想方案」脱离「现实条件」。培训成本、工作流整合难度、兼容性要求,都会直接影响后面实施步骤的设计——正因为有这些约束,实施计划才会包含「试点项目」和「渐进迁移」这类稳健策略。

实施:把决策翻译成行动清单

AR-001 给出了六步实施计划:

  1. 开发团队接受培训,学习并熟悉 Rust;
  2. 用 Rust 创建一个新项目作为试点(trial basis),评估其兼容性与适用性;
  3. 逐步迁移用 C 和 C++ 编写的现有系统到 Rust;
  4. 与 Rust 社区合作,探索可用的工具和库以改进开发工作流;
  5. 定期监控 Rust 的性能,并与现有语言的性能进行比较;
  6. 采取长期策略,在培训、集成成本与使用 Rust 的潜在收益之间取得平衡。

这份清单体现了低风险落地的思路:先培训、再试点、后渐进迁移、持续度量、长期权衡。它没有把「采用 Rust」当作一步到位的命令,而是拆成了可执行、可验证的连续动作。对于任何语言/框架选型类 ADR,这六步都是可以直接套用的模板。

理由:用技术事实支撑结论

AR-001 的 Rationale 是全文的技术核心:

我们采用 Rust,是因为它的独特特性旨在提供内存安全与安全保证,同时保持性能与效率。Rust 强大的类型系统、借用检查器(borrow checker)和内存安全理念,使其非常适合开发性能关键型与安全关键型应用。此外,Rust 拥有庞大的开发者社区,使我们能够获得支持开发工作流的各种工具、库与生态系统。虽然 Rust 有学习曲线,但我们相信采用 Rust 的收益超过成本。

这里点名了三个可被独立验证的技术事实:

  • 类型系统:Rust 的强类型系统在编译期就能拦截大量类型错误;
  • 借用检查器(borrow checker):所有权(ownership)与借用(borrowing)规则在编译期检查,杜绝悬垂引用与数据竞争;
  • 内存安全理念:默认无垃圾回收、无缓冲区溢出,从而覆盖问题陈述中 C/C++ 的核心痛点。

理由段与问题段、考量段形成闭环:问题要「内存安全 + 高性能」,理由就用「类型系统 + borrow checker + 零成本抽象」来回应;考量提到「学习曲线」,理由就承认「存在学习曲线,但收益超过成本」。这正是优秀 ADR 的写法——每个理由都应能追溯到某个考量或约束。

后果:同时写下收益与代价

AR-001 的 Consequences 列了五条,且刻意同时覆盖正反两面:

  1. 成本面:采用 Rust 需要在时间与资源上大量投入,用于培训开发人员并整合进现有工作流;
  2. 风险面:可能在一定程度上造成与现有系统的兼容性问题,需要重构和修改;
  3. 组织面:可能吸引希望参与激动人心项目的 Rust 开发者,扩大能为本项目贡献的开发者群体;
  4. 收益面:与现有语言相比,可能带来性能、效率和安全性的提升;
  5. 收益面:最终有可能减少应用中的安全漏洞。

这份清单展示了 Consequences 的正确打开方式:不粉饰、不夸大。第 1、2 条是「变得更难的部分」,第 3、4、5 条是「变得更容易的部分」。仓库写作规范 skills/architecture-decision-record-skill/reference/writing-guide.md 明确要求 Consequences 段「同时覆盖变容易和变困难的部分」,并建议补充「该决策触发的后续 ADR」与「事后的复盘机制」——例如一条大决策往往会连锁触发若干小决策,需要单独记录。

仓库中的配套资源:模板、多语言与写作规范

这条 Rust ADR 并不是孤立文档,它在仓库中拥有完整的配套生态:

1. 多语言镜像。 仓库按 locales/ 目录组织 30 种语言的内容,同一条决策在 locales/da-001/eksempler/programmeringssproget-rust/README.md、locales/en-001/examples/rust-programming-language/README.md、locales/zh-001/示例/rust编程语言/README.md 等位置内容一一对应,便于跨团队、跨地区复用。

2. 模板对照。 本仓库的 MADR 模板 locales/da-001/skabeloner/skabelon-til-beslutningspost-fra-madr-projektet/README.md 提供了「上下文与问题描述 → 决策驱动力 → 候选选项 → 决策结果(含正/负后果)→ 选项优缺点 → 链接」的完整骨架,AR-001 的写法与它高度兼容;仓库还收录了 Nygard、Tyree & Akerman、arc42、Alexandrian、Planguage 等多套模板,入口见 README.md 的 Templates 一节。

3. 写作规范。 skills/architecture-decision-record-skill/SKILL.md 与 skills/architecture-decision-record-skill/reference/writing-guide.md 总结了写好 ADR 的检查清单:一条 ADR 只记录一个决策;Context 要写组织现状与真实约束;Decision 要明确不摇摆;Consequences 要写后续影响与后续 ADR;必要时可用 fitness function 把决策变成可自动校验的代码。

4. 佐证性示例。 前述 locales/zh-001/示例/编程语言/README.md 提供了更宏观的视角:它把「前端 TypeScript、后端 Rust」作为整体语言策略,并补充了 Rust 的负面考量(生态系统相对较小、直接内存访问需 unsafe),与 AR-001 互为印证。

如何在自己的项目里复用这条 ADR

如果团队正面临类似的语言选型,可以直接按 AR-001 的骨架起草自己的记录:

  1. 先写元信息:编号、标题、日期、状态(proposed → accepted);
  2. 写问题陈述:指出现有语言的具体痛点(如内存安全问题),并给出期望目标;
  3. 列考量维度:内存安全、性能、社区、学习曲线、工具生态、兼容性——按团队实际情况增删;
  4. 写约束:培训成本、工作流整合、兼容性要求等不可突破的边界;
  5. 列实施步骤:培训 → 试点 → 渐进迁移 → 社区协作 → 性能监控 → 长期权衡;
  6. 写理由:每个技术论点(如 borrow checker、类型系统)都要能被独立验证;
  7. 写后果:同时列出代价、风险与收益,并注明可能的后续 ADR。

配合仓库提供的 MADR 模板与 writing-guide 检查清单,团队成员可以快速产出结构一致、可追溯、可评审的决策记录,避免「决策只存在于会议纪要里、三个月后无人记得为什么」的常见问题。

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