Day28-29｜7.2.6 体系结构文档化：把架构决策写成可沟通、可验证、可演化的工程资产

对应教材：《系统架构设计师教程（第2版）》第7章“系统架构设计基础知识”——7.2.6 体系结构文档化。

学习定位：本节属于上篇“综合知识”中架构设计方法的核心内容，也是案例分析和论文写作的共同基础。架构不是只存在于架构师脑中的图，也不是一张漂亮的框图；只有把关键决策、约束、视图、接口、质量属性和演化依据记录下来，架构才能被团队理解、实现、评审和维护。

一、为什么体系结构文档化是高级考试的高频能力

初学者常把“架构文档”理解成项目立项书中的一张系统拓扑图。这样的理解过于狭窄。体系结构文档化解决的是一个工程沟通问题：不同角色需要从不同角度理解同一个系统，并据此作出不同决策。

产品负责人关心系统边界、业务能力和交付范围；开发人员关心模块职责、接口、依赖和扩展点；测试人员关心可验证的质量目标和异常场景；运维人员关心部署单元、资源、监控、容灾和升级方式；安全人员关心信任边界、身份、权限、审计和数据保护；架构师则需要确保这些视角之间不互相矛盾。单一视图无法同时满足所有角色，因此需要以体系结构为中心组织一组相互关联的视图。

考试中，题目往往不会直接问“文档化的定义”，而会给出以下情境：团队对模块边界理解不一致、架构决策无法追溯、部署图与代码结构不一致、性能目标没有验证方法、系统变更后文档失真。答题时要指出，问题的根因不仅是“沟通不足”，更是架构信息没有按照利益相关者、关注点和视图进行结构化记录，也没有建立评审和维护机制。

二、文档化的目标、原则和产出

体系结构文档化通常有四个目标。

1. 沟通：为架构师、开发、测试、运维、业务和管理者提供共同语言。
2. 决策记录：说明为什么选择某种架构、技术或部署方案，而不是只记录最终结果。
3. 实现指导：把系统分解、接口约束、数据责任和运行约束传递给实现团队。
4. 验证与演化：让质量属性能够被检查，让未来变更可以判断影响范围。

好的架构文档应遵循以下原则：

架构文档不等于所有设计文档。数据库表结构、接口详细字段、源代码注释、测试用例和运维手册都有自己的职责，但它们应与架构文档建立链接。架构文档回答“系统如何组织以及为什么这样组织”，详细设计回答“某个部件具体如何实现”。

三、先写关注点，再选择视图

文档化的起点不是打开绘图工具，而是建立“利益相关者—关注点—视图—证据”的映射。

可用下面的关系理解文档结构：

业务目标 → 架构关注点 → 架构视图 → 设计决策 → 实现与验证证据 → 变更记录

例如，业务目标是“订单高峰期仍能稳定下单”，架构关注点包括吞吐量、响应时间、可用性和削峰能力；对应视图可以包括上下文视图、运行视图、部署视图和数据视图；决策可能是引入消息队列、将库存扣减设计为幂等操作并采用分库分表；证据则包括压测结果、故障演练记录和幂等测试用例。这样写出来的文档才形成闭环。

四、架构文档的核心内容

4.1 概述与范围

开篇应说明系统目的、业务范围、非目标、读者、术语、版本和文档状态。尤其要写清“系统不负责什么”，因为边界不清会导致模块职责、接口责任和故障归属不断漂移。

4.2 上下文视图

上下文视图展示系统与用户、外部系统、设备、组织和环境之间的关系。它不宜过早陷入类、表和中间件细节，重点是回答：系统服务谁？接收什么输入？输出什么结果？依赖哪些外部能力？哪些数据跨越系统边界？

文字版示例：

用户端 → 订单平台 → 支付平台、库存平台、物流平台；订单平台还向消息平台发布订单事件，并将审计事件写入安全审计中心。

如果外部系统的可用性、延迟或数据格式会影响本系统，应在上下文说明中记录约束，而不能只把外部系统画成一个没有属性的方框。

4.3 逻辑视图

逻辑视图说明系统的主要职责分解，例如用户接入、订单、库存、支付、履约和审计等模块。每个模块至少应记录职责、输入输出、依赖、拥有的数据以及禁止承担的职责。禁止事项很重要，它能防止公共模块逐渐变成“万能服务”。

4.4 开发视图

开发视图面向代码组织，描述组件、包、仓库、公共库、构建单元和依赖方向。要特别标明依赖规则，例如“领域层不得直接依赖基础设施层实现”“公共库只提供通用能力，不包含具体业务规则”。开发视图不必复制全部目录树，而要突出架构约束和容易违反的边界。

4.5 运行视图

运行视图描述运行时对象如何协作，包括同步调用、异步消息、事件流、缓存、事务、超时、重试、熔断和补偿。很多案例题给出“服务调用链很长、消息重复消费、请求超时后重复扣款”等问题，本质上都需要通过运行视图说明交互协议和故障处理。

4.6 部署视图

部署视图描述软件单元部署到节点、容器、可用区、网络区域和存储资源的方式。应写明负载均衡、服务发现、伸缩策略、主备或多副本关系、数据复制方向、灾备位置以及安全边界。部署图如果没有容量、故障域和恢复目标，就不能支撑高可用结论。

4.7 数据视图与安全视图

数据视图记录核心数据的所有权、生命周期、读写路径、一致性要求、主数据来源、缓存策略、备份和归档策略。安全视图记录身份认证、授权、密钥、敏感数据、信任边界、审计和安全事件响应。对于高级系统架构师，安全不应作为最后附加的一页，而应与数据、接口、部署视图交叉关联。

五、用架构决策记录（ADR）保存“为什么”

架构图容易记录“是什么”，却经常遗漏“为什么”。建议为每个重要决策建立简短的架构决策记录，至少包括：编号、标题、状态、背景、驱动因素、候选方案、选定方案、权衡、后果、风险、关联需求和复审条件。

例如：

ADR-007：订单状态变更采用事件发布。

背景：订单服务的状态变化需要通知库存、支付和物流，直接同步调用会形成较长链路。

选择：订单服务在本地事务提交后发布领域事件，下游采用幂等消费者处理；对必须立即返回的校验仍采用同步接口。

权衡：降低核心链路耦合和峰值压力，但引入最终一致性、重复消息和事件追踪成本。

后果：需要事件唯一标识、消费位点、重试队列、补偿任务和跨服务监控。

ADR 的价值不在于形式，而在于把隐含知识显性化。当人员更替、需求变化或技术条件改变时，团队可以根据原始约束判断决策是否仍然成立，而不是凭记忆争论。

六、架构图如何画得可读、可维护

架构图至少要有标题、范围、图例、版本和说明。图中元素应使用稳定的领域术语，连线应有方向和含义，必要时标注协议、数据类型、同步或异步性质。不要把几十个组件挤在一张“总图”里；总览图用于定位，细节图用于解释。

推荐采用逐级下钻：

系统上下文图 → 容器或子系统图 → 组件图 → 关键运行场景图 → 部署与故障域图

每张图只表达一个主要问题。例如，部署图回答“部署在哪里、如何隔离和容灾”；调用时序图回答“请求如何经过哪些组件”；数据流图回答“数据如何产生、转换、存储和传播”。如果一张图同时承担所有问题，读者就很难判断每个元素的含义。

由于实际博客主题对流程图语法和代码块的渲染可能不一致，本文课程中的图示优先采用文字关系和表格表达；在企业项目中可以使用统一的绘图工具，但必须保留图的源文件和版本记录，避免只能查看图片而无法维护。

七、文档质量检查与维护机制

发布前可以从五个方面复核：

1. 完整性：是否覆盖范围、关键视图、质量属性、接口、数据、安全和部署？
2. 一致性：同一组件在不同视图中是否使用同一名称？边界和依赖是否矛盾？
3. 可追踪性：关键决策能否追溯到需求、风险和验证证据？
4. 可验证性：性能、可用性、可扩展性等目标是否有指标和验证方法？
5. 时效性：是否有负责人、版本号、变更触发条件和复审周期？

文档维护应嵌入变更流程。当发生接口变化、数据模型变化、部署拓扑变化、重大故障、质量目标变化或技术选型变化时，应同步检查相关视图和 ADR。可以把“架构文档更新”作为架构评审和发布清单中的必选项，也可以在代码仓库中将文档与源代码放在同一版本体系内。

常见反模式包括：

• 事后补文档：项目结束才整理，丢失了真实决策背景。
• 图形中心主义：图很精美，但没有职责、约束、指标和证据。
• 复制粘贴失真：多个文档分别维护同一接口和组件信息，修改后互相矛盾。
• 无主文档：所有人都可以修改，却没有审阅者和最终责任人。
• 过度详细：把实现细节全部写入架构层，导致文档无法随系统演化。

八、案例分析：物流平台的架构文档体系

某物流平台包含下单、运单、分拨、计费、司机端和客户查询功能，要求高峰期支持大量订单，核心轨迹数据可追溯，部分外部承运商接口质量不稳定。项目组原有一张系统总图，但开发、运维和安全团队对数据主责、重试边界和灾备范围理解不同。

文档化可以按以下顺序展开：

第一，建立上下文视图，明确客户、司机、承运商、地图服务、支付平台和消息平台的边界，并记录外部接口的延迟、限流和可用性约束。

第二，建立逻辑视图，划分订单、运单、轨迹、计费和通知等职责，明确运单服务拥有运单主数据，轨迹服务负责位置事件接收与查询，不允许通知模块直接修改运单状态。

第三，建立运行视图，说明下单同步校验、运单事件异步传播、承运商回调去重、失败消息重试和人工补偿流程。对“回调重复”和“外部接口超时”分别记录处理策略。

第四，建立部署视图，将接入层、核心服务和数据存储分布到不同故障域；轨迹写入采用可水平扩展的存储，查询侧通过缓存和读副本承担高并发访问。

第五，建立数据和安全视图，标明司机身份、客户联系方式和轨迹数据的敏感级别，记录访问控制、脱敏、加密、审计和保留期限。

第六，使用 ADR 记录“为何轨迹事件采用追加式写入”“为何外部承运商采用适配器隔离”“为何通知采用最终一致性”等决策，并为关键质量属性关联压测、故障演练和安全测试证据。

这样形成的文档，不只是交付物，更是后续扩展新承运商、调整存储方案和处理生产故障时的决策依据。

九、综合知识练习

练习1：单项选择

以下哪项最能体现架构文档与普通模块说明的区别？

A. 记录每个类的全部属性和方法
B. 记录系统关键结构、约束、决策及其对质量属性的影响
C. 只记录项目最终采用的中间件版本
D. 只绘制服务器和网络设备拓扑

答案：B。 架构文档关注影响系统整体组织和质量属性的结构、决策与约束；类级细节和设备清单只能覆盖局部问题。

练习2：多项选择

下列哪些内容适合纳入体系结构文档？

A. 利益相关者及其关注点
B. 关键架构决策及权衡
C. 关键质量属性的指标与验证方式
D. 所有业务代码的逐行解释
E. 部署故障域和恢复目标

答案：A、B、C、E。 D 属于实现细节，不能作为架构文档的主体；必要时可以通过链接关联，而不是全部复制。

练习3：案例题

某电商系统的文档包含一张“微服务架构图”，但没有说明服务边界、数据所有权、同步异步关系、性能指标和技术选型原因。上线后库存服务与订单服务出现双写不一致，团队无法判断原设计是否允许最终一致性。请指出文档存在的主要问题，并给出改进方案。

参考答案：

1. 视图单一，只有静态结构，没有上下文、逻辑、运行、数据、部署和安全等视图，无法表达交互和运行约束。
2. 服务边界不清，没有记录每个服务的职责、拥有的数据和禁止事项，导致订单与库存出现重复写入。
3. 缺少一致性决策，没有说明哪些操作要求强一致、哪些允许最终一致，也没有记录事务边界、事件唯一标识、幂等和补偿策略。
4. 缺少质量属性指标和验证证据，“高并发、可靠”无法被检查。
5. 缺少 ADR，技术选择和权衡不可追溯。

改进时应先补充上下文和利益相关者关注点，再建立逻辑、运行、数据和部署视图；明确库存数据的唯一所有者，规定订单状态与库存扣减的交互协议；对异步方案补充本地事务、事件发布、幂等消费、重试、死信和补偿机制；为响应时间、吞吐量、可用性和数据一致性建立可量化指标；最后将重大决策写入 ADR，并把压测、故障演练和一致性测试作为关联证据。

十、论文写作素材

当论文题目要求“论述软件架构文档化及其作用”时，可以采用以下结构：

第一段写项目背景、规模、核心业务和质量目标，说明利益相关者多、系统复杂、需要共同架构语言。第二段说明自己如何识别利益相关者和关注点，并建立上下文、逻辑、开发、运行、部署、数据和安全视图。第三段重点写一个真实的架构决策，包含背景、候选方案、权衡和最终后果。第四段写如何通过评审、指标、压测、演练和安全测试验证架构。第五段写需求变化或故障发生后，如何更新视图、ADR和路线图。结尾总结文档化对沟通、实现、验证和演化的价值。

可直接使用的论述句式是：

在本项目中，我没有把架构文档等同于静态拓扑图，而是围绕利益相关者的关注点建立多视图文档，并用架构决策记录保存方案选择的背景、权衡和后果。对于每一个重要质量属性，我同时记录目标指标、设计措施和验证证据，从而使架构能够被评审、被实现，也能够在需求变化后被追踪和演化。

十一、今日复盘

今天必须掌握的不是某一种画图工具，而是以下主线：

谁需要理解 → 关心什么 → 用什么视图表达 → 做了什么决策 → 如何验证 → 变化后如何维护。

请用自己的话回答三个问题：

1. 为什么一张系统总图不能替代完整的架构文档？
2. ADR 与普通技术说明的核心区别是什么？
3. 如果文档中写“系统具有高可用性”，还必须补充哪些内容才能使结论可验证？

建议把案例中的物流平台替换成自己熟悉的业务，至少画出或写出上下文、逻辑、运行和部署四类视图，并为一个关键技术决策写一份 ADR。完成这一步，才算真正把“体系结构文档化”从概念转化为架构实践能力。