记录软件架构
编写架构文档是为了回答利益相关者在系统生命周期内可能会反复向你询问的问题：这个系统是如何组合起来的？ 为什么要这么设计？ 我该在哪里修改 X？ 在 Y 条件下它能支撑住吗？ 好的文档可以一次性书面回答这些问题，且形式便于每位读者理解。
本技能提供了一套用于编写文档以及审查他人所写文档的方法。它基于开放、免费的标准和模型，而非任何单一版权文本：
- ISO/IEC/IEEE 42010 —— 架构描述的国际标准。它定义了通篇使用的词汇：利益相关者（stakeholder）、关注点（concern）、观点（viewpoint）、视图（view）、模型（model）、架构决策（architecture decision）、理由（rationale）。
- C4 模型（Simon Brown） —— 一组轻量级的结构化图表，分四个缩放层次：上下文、容器、组件、代码。
- 4+1 视图模型（Philippe Kruchten） —— 五个并行的视角：逻辑视图、过程视图、开发视图、物理视图，以及将它们串联起来的场景视图。
- arc42 —— 一个知识共享的文档模板，其章节结构为完整的架构描述提供了实用的骨架。
- 架构决策记录（ADR，由 Michael Nygard 推广的格式） —— 每个重要决策对应一个简短文件。
方法
文档应由谁阅读以及他们需要决定或做什么来驱动。请按以下顺序工作。
-
识别利益相关者及其关注点。 列出依赖该架构的人（开发者、运维人员、安全审查员、产品负责人、集成商、审计员）以及每个人需要文档回答的问题。关注点是某个对某人重要的问题或质量属性：“我能否在不宕机的情况下部署？”、“客户数据存在哪里？”、“我如何添加新的支付提供商？”。关注点决定了后续的一切。参见
references/viewpoints-and-views.md。 -
选择能够覆盖关注点的观点。 观点是一种可重复使用的视图类型：它定义了构建某一类表示形式的惯例（展示哪些元素、哪些关系、使用何种表示法）。选择最小的观点集合，使其共同覆盖所有重要的关注点。不要编写没有人需要的视图。参见
references/view-catalog.md。 -
构建视图。 每个视图都是从某个观点出发对系统的一种表示：一幅图表加上解释其含义的文字。大多数系统需要结构视图（系统的组成部分及其依赖关系）、运行时视图（执行时发生的情况：进程、流程、交互）和部署视图（软件如何映射到基础设施）。对时间或顺序至关重要的部分，还需添加行为视图。C4 层次和 4+1 视角是经过验证的具体实现方式。参见
references/view-catalog.md。 -
捕获决策及其理由。 架构文档中最有价值且最常缺失的部分是为什么。将每个重要决策（背景、考虑过的选项、做出的选择及其后果）记录为架构决策记录。理由是让后续人员能够安全修改系统而非猜测其意图的关键。参见
references/decisions-and-rationale.md。 -
组装描述并添加引导。 一堆视图堆叠起来不是文档。需要添加连接性内容：一页的系统概述、范围和上下文说明、术语表，以及明确说明视图之间如何关联（同一元素在不同视图中出现是读者困惑的主要来源，因此必须解决）。使用
references/documentation-template.md作为完整的章节骨架。 -
在提交前进行审查。 对照
references/review-checklist.md审查文档。两个主要失败模式是不完整（某个关注点没有任何视图覆盖）和不可读（图表缺少图例、未定义的术语、没有说明读者正在看什么）。
如何使用本技能
- 从零开始 → 遵循上述六个步骤，使用
references/documentation-template.md作为目标结构。 - 决定写什么 →
references/viewpoints-and-views.md（关注点 → 观点）和references/view-catalog.md（视图类型目录）。 - 记录决策 →
references/decisions-and-rationale.md（ADR 格式及示例）。 - 审查现有文档 →
references/review-checklist.md。 - 在框架之间进行选择或将一个映射到另一个 →
references/frameworks-map.md。
原则
- 为读者而写，不为追求完整而写。 每个视图、图表和段落都应能追溯到某个利益相关者的关注点。如果你说不出谁需要它，就删掉它。
- 每个图表都需要图例。 “看起来很明显”的表示法实际上并不明显。说明方框和线条的含义。没有解释的图表就是等待出错的猜测。
- 边做边记录理由。 决策在做出时捕获成本最低，事后重构成本极高。
- 保持与代码的同步并及时更新。 与实际情况脱节的文档比没有文档更糟糕，因为人们会信任它。宁愿维护一份较小的文档，也不要一份大量文字但无人维护的文档。
- 根据系统风险确定深度。 对于出错了代价高的部分，详细记录；其余部分略写即可。