总体设计文档到底该写些什么？ | 架构师之路（15）

《架构师之路：架构设计中的100个知识点》 15.总体设计文档

总体设计，是架构师经常要写的文档。

总体设计文档，一般要写些什么呢？

除了需求模块，技术的部分至少应该包含设计目标，系统架构，模块简介与设计折衷这四个部分。

需求模块一般怎么写？

可以用产品的语言描述需求，怕麻烦的话，也可以拷贝需求文档的链接。

设计目标模块一般怎么写？

设计目标又分为功能目标与性能目标：

（1）功能目标，是对产品需求的技术描述；

（2）性能目标，是根据业务数据对系统性能进行的评估；

性能目标非常重要，它很可能会影响整个设计方案。

系统架构与模块简介一般怎么写？

（1）系统架构，一般会画一个架构图，并配以文字对架构进行简要说明；

（2）模块简介嘛，是对架构图中多个模块的说明介绍；

总体设计文档中，哪个模块最为重要？

设计折衷这个模块最为重要。

为什么设计折衷最为重要呢？

总体设计文档撰写完之后，要进行总体设计评审。总体设计评审的内容，主要就是方案的设计折衷，讨论各个方案的优缺点，并确认最终使用哪种方案。

因此，总体设计文档里一定要说明，多个方案的优缺点，以供设计评审时讨论。如果设计文档里只有一种方案，那设计评审的意义便不大了，会演变为评审委员会帮助架构师思考方案的不足，以及临时提供解决方案。

另外，在总体设计评审过后，也一定要更新文档，说明最终使用了哪种方案，以及为什么使用这种方案。有时候因为排期或者其他原因，不一定采用了最优的设计方案，此时更应该在文档中记录决策的过程与原因。

如果不记录，别人拿到你设计的系统，设计方案可能完全就是个谜。

另外，设计折衷是架构师进行自我辩解的最佳机会：因为项目进度，因为历史遗留问题，我不得不采取了这样一坨设计方案，情有可原，以后不要再骂我了。

简单总结：

（1）总体设计文档，一般包含需求、设计目标、系统架构、模块介绍、设计折衷这5个部分；

（2）其中最重要的，是设计折衷。

知其然，知其所以然。

思路比结论更重要。

补充阅读材料：

《如何写好系统设计文档》

https://www.freecodecamp.org/news/how-to-write-a-good-software-design-document-66fcf019569c/

1. 设计文档要包含哪些内容？

- 需求背景与上下文说明

- 设计目标与里程碑

- 潜在方案与设计折衷

- 测试，监控，告警方案

2. 怎么写设计文档？

- 简洁

- 架构图，表格，数字

- 试着搞笑一点

文章不长，10分钟搞定。