企业官网建设流程全解析

本文以开源仓库 architecture-decision-record 中收录的 MADR 项目决策记录模板 为核心，逐字段拆解该模板的完整结构与填写要点，并结合仓库内 示例 与 配套文档 展示一套可复制、可落地的 ADR 写作流程。读完本文，你将能够：理解 MADR 模板每部分的职责与可选标记；按照模板结构独立撰写一份结构完整、理由充分的架构决策记录；并掌握状态流转、备选方案评估与后果记录等核心实践。

一、MADR 模板是什么：定位与来源

MADR（Markdown Architectural Decision Records）是一套以 Markdown 为载体的架构决策记录模板体系，强调用轻量、易读的文本格式记录软件架构中的重要决策。本仓库在 templates 目录 中收录了 11 套不同的 ADR 模板（如 Michael Nygard、Jeff Tyree & Art Akerman、arc42、EdgeX 等），其中 MADR 项目模板 是结构最为完备、最贴近现代工程实践的方案之一。

从模板目录内的 LICENSE 文件 可以看到，该模板源自adr/madr项目，采用MIT OR CC0-1.0双许可，意味着它可以被自由复制、修改和用于团队内部规范。

MADR 模板的整体骨架如下，本文后续将逐段展开：

# [short title of solved problem and solution] * Status: proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005] <!-- optional --> * Deciders: [list everyone involved in the decision] <!-- optional --> * Date: [YYYY-MM-DD when the decision was last updated] <!-- optional --> Technical Story: [description | ticket/issue URL] <!-- optional --> ## Context and Problem Statement ## Decision Drivers <!-- optional --> ## Considered Options ## Decision Outcome ### Positive Consequences <!-- optional --> ### Negative Consequences <!-- optional --> ## Pros and Cons of the Options <!-- optional --> ## Links <!-- optional -->

二、标题与元数据区块：让每条 ADR 可检索、可追踪

2.1 标题（H1）

模板第一行要求填写# [short title of solved problem and solution]，即"已解决问题与解决方案的简短标题"。这是整条 ADR 的第一检索入口，命名时应做到：

• 一句话说清"问题 + 方案"：例如"选择数据库技术"、"为 REST API 采用 snake_case 命名规范"；
• 与文件名保持一致：仓库文档 File name conventions for ADRs 建议文件名采用"现在时祈使动词短语 + 小写 + 连字符 + .md"的格式，例如choose-database.md、format-timestamps.md，标题应与之呼应，保证文件系统与阅读场景下都能快速定位。

2.2 元数据行（Metadata）

模板在标题下方定义了四行带*前缀的元数据，均以<!-- optional -->标注为可选字段，按需取舍：

关于Status字段，仓库中其他模板提供了更细的枚举可作参考，例如 业务案例模板 明确列出一组取值：proposed, accepted, rejected, deprecated, superseded等。MADR 模板的特殊之处在于superseded by直接内嵌了指向新 ADR 的 Markdown 相对链接（如ADR-0005），从而在决策日志（ADL）内部天然形成一条"决策演进链"。

三、Context and Problem Statement：交代决策背景

这是每条 ADR 的正文起点，模板给出如下指引：

[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]

要点拆解：

• 自由形式、两到三句话：不需要长篇大论，把"我们正在做什么、遇到了什么问题"讲清楚即可；
• 鼓励以问题形式收束：例如"我们该如何在 MySQL 与 PostgreSQL 之间做出选择？"，把决策点显式摆出来；
• 背景要包含组织与业务语境：仓库文档 Suggestions for writing good ADRs 进一步强调，好的 Context 应说明"组织所处情况与业务优先级"，并纳入团队技能构成等社会性考量——这些往往才是决策的真正约束。

仓库示例 Choosing a Database Technology 提供了标准写法：

我们正在设计一个新应用，需要以可扩展、高性能的方式存储和检索数据。我们识别出三类常用数据库技术：关系型数据库、文档型数据库和事件型数据库。

一句话交代了项目阶段（设计新应用）、核心诉求（可扩展、高性能）、候选空间（三类技术），为后续的决策驱动与选项评估铺好了地基。

四、Decision Drivers：明确决策驱动力（可选）

## Decision Drivers是 MADR 模板区别于早期模板的标志性章节，用于在评估选项之前，先固化"哪些力量在推动这次决策"。模板示例：

* [driver 1, e.g., a force, facing concern, …] * [driver 2, e.g., a force, facing concern, …] * … <!-- numbers of drivers can vary -->

常见的 driver 类型包括：

• 约束类：预算上限、团队技能栈、交付期限；
• 质量属性类：可扩展性、性能、可维护性、安全性；
• 一致性类：与既有代码/约定保持一致；
• 合规类：行业规范、监管要求。

仓库示例 snake_case v. camelCase for a REST API 列出了四条可借鉴的 drivers：

• 与项目现有命名约定保持一致；
• 对 API 协作方的可读性与清晰度；
• 与 REST API 命名行业最佳实践对齐；
• 实现与维护的便利性。

提前写下 drivers 的价值在于：后续"Decision Outcome"中的理由（justification）可以直接引用这些驱动点，形成"驱动 → 选项 → 决策 → 后果"的闭环论证，而不是事后找理由。

五、Considered Options：穷举候选方案

## Considered Options * [option 1] * [option 2] * [option 3] * … <!-- numbers of options can vary -->

本小节要求列出所有被认真评估过的候选方案，数量不固定（模板注释明确说明可以变化）。实践建议：

• 至少列出 2～3 个真实候选，避免"只有一个选项的假决策"；
• 选项可以是技术选型（React/Vue/Svelte）、也可以是规范选择（snake_case/camelCase）、流程选择等；
• 每个选项后续都要在"Pros and Cons of the Options"章节拥有独立小节——不要列出不打算评估的占位选项。

仓库示例 React Front-End JavaScript Library 即列出了 React、Vue、Svelte 三个候选，并在 Rationale 中逐一回应。

六、Decision Outcome：结论与后果

6.1 决策结论

## Decision Outcome Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)].

模板要求用一句话给出选定的选项 + 理由，理由的典型写法模板给出了三种模式：

• 命中否决性标准：only option, which meets k.o. criterion decision driver——只有该选项满足某个一票否决的驱动条件；
• 化解核心矛盾：which resolves force——该选项直接化解了 Decision Drivers 中列出的某个力量；
• 综合评分最优：comes out best (see below)——在下方 Pros and Cons 中综合比较后胜出。

6.2 Positive / Negative Consequences

### Positive Consequences <!-- optional --> * [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …] ### Negative Consequences <!-- optional --> * [e.g., compromising quality attribute, follow-up decisions required, …]

决策不是终点，后果才是真正影响后续工程的起点。模板把后果拆成正面与负面两组，均标记为可选：

• 正面后果：如质量属性满意度提升、带来后续决策需求、团队能力沉淀等；
• 负面后果：如牺牲了某个质量属性、产生了必须跟进的后续决策、引入了学习成本等。

仓库文档 Suggestions for writing good ADRs 对本小节给出了三条深化建议：

1. 说明决策随之而来的影响、产出与后续事项；
2. 记录后续 ADR 需求——大决策往往触发一串小决策，这是 ADR 最常见的连锁效应；
3. 纳入事后复盘机制——典型做法是决策一个月后回看 ADR，与实际发生的情况比对，以便学习成长。

示例 Choosing a Database Technology 的 Consequences 部分就明确写道："选择文档数据库后，我们需要投入学习并理解所选具体技术，同时确保应用数据模型与文档型数据模型匹配以最大化性能与可扩展性"——同时承认"收益大于成本"。既有成本认知，又有价值判断，是可复制的写法。

七、Pros and Cons of the Options：逐选项打分（可选）

## Pros and Cons of the Options <!-- optional --> ### [option 1] [example | description | pointer to more information | …] <!-- optional --> * Good, because [argument a] * Good, because [argument b] * Bad, because [argument c] * … <!-- numbers of pros and cons can vary --> ### [option 2] ### [option 3]

每个候选选项各占一个 H3 小节，内部结构统一：

• 可选的一段补充说明：可以是示例、描述或指向更多信息的指针；
• 一组Good, because ...（优点）与Bad, because ...（缺点）列表，数量不限。

写作建议：

• 优点与缺点必须基于 Decision Drivers 展开，保持前后逻辑一致；
• 允许"优缺点并存"：例如示例 React Front-End JavaScript Library 在 Rationale 中给出 React 的组件化、声明式、社区庞大、性能好、灵活性强等优点，同时在 Consequences 中坦诚列出学习曲线、构建工具复杂度、旧浏览器兼容性等缺点——不回避缺点，是 ADR 可信度的来源；
• 该章节标记为可选：若只有一个候选或理由已在 Decision Outcome 中充分说明，可整章省略。

八、Links：链接到相关 ADR（可选）

## Links <!-- optional --> * [Link type] [Link to ADR] <!-- example: Refined by ADR-0005 --> * … <!-- numbers of links can vary -->

Links 章节用于把当前 ADR 与决策日志中的其他 ADR 关联起来，模板给出的示例是Refined by ADR-0005。常见的链接类型：

• Refined by：被某条新 ADR 细化/精化；
• Superseded by：被某条 ADR 取代（与元数据区 Status 呼应）；
• Related to：与某条 ADR 相关但非替代关系；
• Extends：在既有决策上扩展。

注意：这里使用的是相对于当前 ADR 文件位置的 Markdown 链接（如0005-example.md），在实际项目中应结合团队的文件组织方式（常见为docs/adr/目录 + 编号前缀，如0005-example.md）书写。

九、用 MADR 模板写一条完整 ADR：结合仓库示例的实战演练

综合以上字段，参照仓库 示例 的写作风格，一条符合 MADR 模板的完整 ADR 应长这样（以数据库选型为例，融合模板结构与示例内容）：

# 为订单服务选择文档型数据库 * Status: accepted * Deciders: 订单服务架构组（张伟、李娜、王强） * Date: 2026-10-12 Technical Story: https://ticket.example.com/ord-2331 ## Context and Problem Statement 我们正在设计一个新应用，需要以可扩展、高性能的方式存储和检索数据。我们识别出三类常用数据库技术：关系型数据库、文档型数据库和事件型数据库，需要为订单服务做出选择。 ## Decision Drivers * 数据模型需要随业务快速演进，避免频繁的 schema 迁移 * 需要水平扩展以支撑高读写吞吐 * 不要求复杂事务与强一致的多表关联 * 团队对 NoSQL 生态已有一定实践经验 ## Considered Options * 关系型数据库（MySQL / PostgreSQL） * 文档型数据库（MongoDB / DynamoDB） * 事件型数据库（Kafka / Pulsar） ## Decision Outcome Chosen option: "文档型数据库"，because 只有它同时满足"数据模型可演进"与"水平扩展"两个关键驱动，且综合评分最优（见下文）。 ### Positive Consequences * 数据模型演进无需修改 schema，上线节奏更快 * 内置分片与复制，读写吞吐可水平扩展 * 索引与查询能力满足核心检索场景 ### Negative Consequences * 需要投入学习所选具体技术（如 MongoDB）的运维知识 * 需要谨慎设计文档模型以匹配访问模式，否则性能与扩展性会打折扣 * 后续可能需要补充 ADR 记录分片键设计、一致性策略等细化决策 ## Pros and Cons of the Options ### 关系型数据库 * Good, because 强一致性与事务支持完善，数据完整性有保障 * Bad, because schema 固定，业务模型演进时迁移成本高 * Bad, because 水平扩展需要额外的分库分表方案，运维复杂 ### 文档型数据库 * Good, because schema-less 模型支持字段级演进 * Good, because 内建分片与复制，天然支持水平扩展 * Bad, because 复杂跨文档事务支持有限，需在应用层补偿 ### 事件型数据库 * Good, because 完整记录每次数据变更，天然支持审计与事件溯源 * Bad, because 数据检索与即席查询能力弱，不适合作为主存储 ## Links * Refined by ADR-0006（分片键设计） * Superseded by 无

十、配套实践：让 MADR 模板真正落地

模板只是骨架，要产出高质量的 ADR，还需配合仓库中的三条配套实践：

10.1 理解 ADR 概念体系

• ADR（Architecture Decision Record）记录一次重要架构决策及其上下文与后果；
• AD（Architecture Decision）是满足重要需求（ASR）的软件设计选择；
• ADL（Architecture Decision Log）是项目或组织中所有 ADR 的集合；
• ASR（Architecturally-Significant Requirement）是对系统架构有可度量影响的需求。

完整定义见仓库文档 What is an Architecture Decision Record。

10.2 遵循好 ADR 的四个特征

仓库文档 Suggestions for writing good ADRs 提出好 ADR 的四条标准：

• Rationale（有理由）：说明做该决策的原因，含上下文、候选优劣、特性对比、成本/收益讨论；
• Specific（聚焦）：每条 ADR 只讲一个决策；
• Timestamps（有时间戳）：标注每项内容的写作时间，尤其对成本、进度、扩展性等随时间变化的内容；
• Immutable（不可变）：不修改 ADR 中既有信息；需要变更时，通过追加新信息或新建 ADR 来取代旧 ADR——这与模板中superseded by的设计完全一致。

10.3 从团队协作流程起步

仓库文档 How to start using ADRs 给出了启动 ADR 实践的五个讨论维度，可直接与 MADR 模板各章节对应：

十一、小结：MADR 模板的价值与适用场景

相比仓库收录的其他模板，MADR 模板的特色在于决策驱动（Decision Drivers）与备选方案评估（Pros and Cons）的显式分离，它强制作者先回答"什么力量推动决策"，再评估"每个选项的优劣"，最后给出"选择与后果"，形成一条可审计的决策推理链。同时，Status中的superseded by与末尾Links章节让多条 ADR 之间可以互相引用、演进，支撑起可持续维护的架构决策日志（ADL）。

适用场景包括：技术选型（数据库、框架、编程语言、云平台）、接口与规范制定（API 命名、时间戳格式）、流程与组织决策（远程办公、4 天工作周）等。仓库 examples 目录 中的 40 余个示例即为模板在不同场景下的落地范本，可作为直接参考。

快速上手指南：复制 MADR 模板 → 按 文件命名规范 命名（如choose-order-database.md）→ 依次填写元数据、Context、Decision Drivers、Considered Options、Decision Outcome、Pros and Cons、Links → 参照 好 ADR 建议 自检后提交评审。