架构与系统设计 / 系统课时

写一份可评审的架构说明书

写一份可评审的架构说明书

可评审的架构说明书不是把系统知识全部写进去,而是把“为什么这样设计、凭什么接受这些代价、还有哪些风险没解决”组织成一条证据链。本节给出一套精简结构,让评审者能快速定位驱动因素、关键视图、决策、风险和未决问题。

学习目标

  • 用背景、驱动因素、关键视图、决策、风险和未决问题组织架构说明书
  • 让每个重要设计决定都能追溯到具体约束或质量目标
  • 在提交评审前识别缺失证据、隐含假设和尚未关闭的问题

文档的目标是帮助别人做判断

架构说明书首先是一个“决策接口”。评审者读完后,应该能够回答三个问题:系统要解决什么约束最强的问题,当前方案为何优于主要替代方案,以及哪些风险需要接受、缓解或继续验证。

因此,背景只保留会影响设计的事实;技术细节只保留与关键决策相关的部分;已经确定但没有争议的实现约定可以简写。若文档很长却看不出要评什么,通常不是信息不够,而是决策主线被实现细节淹没了。

用六块内容形成证据链

一份精简但可评审的说明书可以按以下顺序组织:

  1. 背景:说明系统边界、主要参与者、现状问题和本次设计范围,让评审者知道“讨论的对象是什么”。
  2. 驱动因素:列出真正约束架构的质量目标、业务约束、合规要求、团队能力或既有系统限制。
  3. 关键视图:只画与本次决策相关的上下文、运行、数据、部署或模块视图,不为“文档完整”堆图。
  4. 架构决策:写明选择、理由、主要替代方案、代价和反转条件,让取舍可追溯。
  5. 风险:记录可能导致目标失败的条件,以及当前缓解措施和验证方式。
  6. 未决问题:明确仍缺什么信息、由谁补齐、补齐后会影响哪个决策。

架构说明书从驱动因素到决策与风险的证据链

这六块不是独立章节的堆叠,而应互相引用。一个关键决策找不到对应驱动因素,往往说明它只是实现偏好;一个高风险项找不到受影响的决策,则说明风险描述过于泛化;一个未决问题没有截止条件,就很容易永久留在文档里。

关键视图只回答关键问题

视图的数量不重要,能否支撑判断才重要。上下文视图适合说明系统边界和外部依赖;运行视图适合解释调用链、异步协作、故障传播和恢复路径;部署视图适合回答隔离、容量和可用性;数据视图适合说明数据所有权、流向和一致性边界。

评审问题 更合适的视图
系统与哪些外部对象交互,边界在哪里 上下文视图
请求、事件或故障如何在组件间传播 运行视图
实例、区域或网络如何承载高可用目标 部署视图
数据由谁拥有,在哪里写入和同步 数据视图

不要为了“关键视图”四个字把所有类型都画一遍。如果本次评审只关注故障恢复,运行视图和部署视图通常比完整模块图更有价值;如果评审重点是数据一致性,则数据边界和写入路径应成为主视图。

决策必须写出取舍与反转条件

一个可评审的决策至少包含五件事:决定了什么、为什么、比较过什么、付出什么代价、什么条件出现时需要重新决策。只写“采用某方案,因为性能更好”无法评审,因为没有明确目标、证据和代价。

可以把每条重要决策压缩成这样的结构:

  • 决定:明确系统将采用的结构或机制。
  • 驱动因素:引用促成这项选择的约束或质量目标。
  • 替代方案:列出真正考虑过的主要方案,以及未选择原因。
  • 代价:说明复杂度、成本、耦合、运维负担或能力损失。
  • 反转条件:写明什么指标、业务变化或外部约束会迫使重新评估。

这样写的好处是,未来系统演进时可以快速判断“原决策还成立吗”,而不必重新猜测当时的设计动机。

风险与未决问题要能够关闭

风险不是“可能有性能问题”这种模糊提醒,而应描述触发条件、影响对象和当前缓解措施。例如,可以写成“当关键依赖超过目标延迟时,主链路可能耗尽连接;当前通过超时、隔离和降级限制传播范围,并通过压测验证容量边界”。

未决问题则必须能在未来变成“已解决”。至少要说明缺少什么信息、由谁提供、会影响哪项决策,以及在什么评审点之前必须获得答案。没有这些要素的未决问题会逐渐变成无人负责的备注。

提交前做一次可评审性检查

交付前从评审者视角快速检查:是否能在几分钟内找到系统边界和最重要的驱动因素;每个关键决策是否都能追溯到至少一个驱动因素;关键视图是否真正支撑了这些决策;风险是否有缓解或验证方式;未决问题是否有关闭条件。

最后再删一次内容:删掉不会改变任何评审判断的背景、重复的实现细节和无法行动的泛泛描述。好的架构说明书不追求“写得全”,而是让评审围绕真正需要判断的取舍展开,并让后续演进能够看见这些取舍最初成立的条件。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

写一份可评审的架构说明书

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通