为什么需要写文档

软件工程师有两大难：1，没有文档；2，写文档。设计文档是用于描述如何去解决一个产品或特性的问题的，好的设计文档可以确保正在做的是正确的事情。

架构设计文档通常又可以分成概要设计文档以及详细设计文档。概要设计文档把握产品架构的宏观方向，而详细设计文档确定微观的代码实现。通常详细设计文档应该由具体负责这个模块实现的人员来完成，只有负责代码落地的人员才最清楚具体的微观问题，其他人员可以参与审阅设计方案、把握正确的方向。在工作中经常会遇到这样的情况：设计人员写完详细设计文档再把文档交付给写代码的人，去要求按这个文档写代码，经常会遇到的矛盾是：负责具体写代码的人觉得这个文档脱离实际没价值，而写文档的人又指责写代码的人员不理解他的意图。 因此，比较合适的方案是 谁负责写代码谁就负责详细设计（这对技术人员的能力要求也较高），其他人员提供检阅与建议，把握风险与方向。

那么如何撰写一个好的架构设计文档呢？这里提出一个常用的架构设计模板，以供参考，如下：

架构设计文档模板

动机介绍

描述需要完成的内容，介绍上下文以及需要达到的目标。

需求分析

以三三制需求分析模型分析客户、用户以及团队的功能、质量与约束需求，首要方针是“价值优先”。

目标非目标

目标与非目标主要是解释本文档做什么与不做什么，定义需要完成的任务与约束边界。

1
2
3

目标：定义本设计文档需要解决的问题以及需要达到的质量指标，是说明需要做什么。

非目标：说明本设计文档的约束，是说明不做什么。

里程碑

计划本身是“无用”的，但是没有计划却是万万不能，通过制定里程碑可以让文档的其他用户知道项目所需要的大概的时间周期。例如，可以按如下格式定义里程碑：

1
2
3
4

开工日期：2020年10月10日
里程碑 1 - 2020年10月30日，完成概要设计文档
里程碑 2 - 2020年11月30日，完成详细设计文档，并且编写完代码
结束日期: 2020年12月30日，完成自我测试、文档、质量保证以及特性交付

设计哲学

产品的设计哲学是产品的宪法，也是产品的灵魂与价值观，是产品的不可违背的最高指导思想，其把握了架构设计的方向，例如:

1
2
3

设计哲学
 - 以客户价值为中心
 - 以持续创新为竞争力

设计原则

架构交付的是功能需求，但是真正的差距体现在非功能需求（质量与约束），因此可以通过制定设计原则确定产品的非功能要素，设计原则是产品的法则，也是架构取舍的依据，例如:

1
2
3
4
5
6
7
8
9
10
11
12
13

设计原则
- 最佳物种原则
- 高内聚低耦合原则
- 可用性原则
- 可靠性原则
- 稳定性原则
- 可服务化原则
- 兼容性、可迁移原则
- 服务化、组件化
- 接口隔离与服务自治
- 用户触达成本原则
- 用户体验原则
- 持续演进原则

设计提案

设计提案可以从三个方面进行考虑：客户想要的、对手怎么做以及自身打算怎么进行，还需要分析每个方案的优点、缺点以及方案取舍的依据。

当前提案

当前方案需要分当前已有的提案、也可包括当前竞争对手的方案，以及客户/用户所期待的方案。

自身提案

提出自身的设计方案，可以提出多个设计方案：比如 提案1，提案2等，确定大的架构设计方向。

提案比较

提出以上方案后，制定技术提案评审表，分析提案的优缺点，确定最终的可选方案。

架构设计

这一部分是最重要、最核心的内容，属于架构设计文档的核心。在确定设计提案后进行概要设计，通常可以采用 4+1 架构设计法完成这一部分内容。如下图：

常用的4+1视图涵盖有物理视图、逻辑视图、处理视图、开发视图以及用例视图，其中与用例视图交叉的部分是描述共同的细节，同时每种视图中又有各自的需求，例如：

• 物理视图关注安装、部署、升级、运维的需求；
• 逻辑视图关注架构设计的功能需求；
• 处理视图关注非功能里的用户运行质量需求；
• 开发视图关注团队的开发质量需求；

跨团队影响

这里阐述需要的团队依赖以及对其他团队的影响。

详细的交付计划

这里可以以表格的方式，制定详细的交付计划。

开放问题讨论

提出需要讨论的问题。

作者与评审人员

确定作者与评审人员信息，例如：

小结

本文提出了一个常用的架构设计模板，希望这个设计模板对大家有用。另作者能力与认知都有限，”我讲的，可能都是错的“[1]，欢迎大家拍砖留念。

作者简介

常平，中科大硕，某AI独角兽深度学习首席软件工程师，前EMC 大数据资深首席工程师，主要工作背景在深度学习、流式大数据、云计算、分布式中间件以及Linux内核。

版权申明

本文的版权协议为 CC-BY-NC-ND license：https://creativecommons.org/licenses/by-nc-nd/3.0/deed.zh

在遵循署名、非商业使用（以获利为准）以及禁止演绎的前提下可以自由阅读、分享、转发、复制、分发等。

参考资料

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