架构与系统设计 / 系统课时
写一份可评审的架构说明书
写一份可评审的架构说明书
可评审的架构说明书不是把系统知识全部写进去,而是把“为什么这样设计、凭什么接受这些代价、还有哪些风险没解决”组织成一条证据链。本节给出一套精简结构,让评审者能快速定位驱动因素、关键视图、决策、风险和未决问题。
学习目标
- 用背景、驱动因素、关键视图、决策、风险和未决问题组织架构说明书
- 让每个重要设计决定都能追溯到具体约束或质量目标
- 在提交评审前识别缺失证据、隐含假设和尚未关闭的问题
文档的目标是帮助别人做判断
架构说明书首先是一个“决策接口”。评审者读完后,应该能够回答三个问题:系统要解决什么约束最强的问题,当前方案为何优于主要替代方案,以及哪些风险需要接受、缓解或继续验证。
因此,背景只保留会影响设计的事实;技术细节只保留与关键决策相关的部分;已经确定但没有争议的实现约定可以简写。若文档很长却看不出要评什么,通常不是信息不够,而是决策主线被实现细节淹没了。
用六块内容形成证据链
一份精简但可评审的说明书可以按以下顺序组织:
- 背景:说明系统边界、主要参与者、现状问题和本次设计范围,让评审者知道“讨论的对象是什么”。
- 驱动因素:列出真正约束架构的质量目标、业务约束、合规要求、团队能力或既有系统限制。
- 关键视图:只画与本次决策相关的上下文、运行、数据、部署或模块视图,不为“文档完整”堆图。
- 架构决策:写明选择、理由、主要替代方案、代价和反转条件,让取舍可追溯。
- 风险:记录可能导致目标失败的条件,以及当前缓解措施和验证方式。
- 未决问题:明确仍缺什么信息、由谁补齐、补齐后会影响哪个决策。

这六块不是独立章节的堆叠,而应互相引用。一个关键决策找不到对应驱动因素,往往说明它只是实现偏好;一个高风险项找不到受影响的决策,则说明风险描述过于泛化;一个未决问题没有截止条件,就很容易永久留在文档里。
关键视图只回答关键问题
视图的数量不重要,能否支撑判断才重要。上下文视图适合说明系统边界和外部依赖;运行视图适合解释调用链、异步协作、故障传播和恢复路径;部署视图适合回答隔离、容量和可用性;数据视图适合说明数据所有权、流向和一致性边界。
| 评审问题 | 更合适的视图 |
|---|---|
| 系统与哪些外部对象交互,边界在哪里 | 上下文视图 |
| 请求、事件或故障如何在组件间传播 | 运行视图 |
| 实例、区域或网络如何承载高可用目标 | 部署视图 |
| 数据由谁拥有,在哪里写入和同步 | 数据视图 |
不要为了“关键视图”四个字把所有类型都画一遍。如果本次评审只关注故障恢复,运行视图和部署视图通常比完整模块图更有价值;如果评审重点是数据一致性,则数据边界和写入路径应成为主视图。
决策必须写出取舍与反转条件
一个可评审的决策至少包含五件事:决定了什么、为什么、比较过什么、付出什么代价、什么条件出现时需要重新决策。只写“采用某方案,因为性能更好”无法评审,因为没有明确目标、证据和代价。
可以把每条重要决策压缩成这样的结构:
- 决定:明确系统将采用的结构或机制。
- 驱动因素:引用促成这项选择的约束或质量目标。
- 替代方案:列出真正考虑过的主要方案,以及未选择原因。
- 代价:说明复杂度、成本、耦合、运维负担或能力损失。
- 反转条件:写明什么指标、业务变化或外部约束会迫使重新评估。
这样写的好处是,未来系统演进时可以快速判断“原决策还成立吗”,而不必重新猜测当时的设计动机。
风险与未决问题要能够关闭
风险不是“可能有性能问题”这种模糊提醒,而应描述触发条件、影响对象和当前缓解措施。例如,可以写成“当关键依赖超过目标延迟时,主链路可能耗尽连接;当前通过超时、隔离和降级限制传播范围,并通过压测验证容量边界”。
未决问题则必须能在未来变成“已解决”。至少要说明缺少什么信息、由谁提供、会影响哪项决策,以及在什么评审点之前必须获得答案。没有这些要素的未决问题会逐渐变成无人负责的备注。
提交前做一次可评审性检查
交付前从评审者视角快速检查:是否能在几分钟内找到系统边界和最重要的驱动因素;每个关键决策是否都能追溯到至少一个驱动因素;关键视图是否真正支撑了这些决策;风险是否有缓解或验证方式;未决问题是否有关闭条件。
最后再删一次内容:删掉不会改变任何评审判断的背景、重复的实现细节和无法行动的泛泛描述。好的架构说明书不追求“写得全”,而是让评审围绕真正需要判断的取舍展开,并让后续演进能够看见这些取舍最初成立的条件。