架构实战营 - 方案设计文档模板

架构实战营课程讲到了 3 类关键的设计文档：备选架构设计文档、详细架构设计文档、方案设计文档。其中前两个是在架构设计阶段由架构师或者架构设计团队完成的，而方案设计文档就是开发人员在项目开发过程中需要完成的文档。如下图清晰的展示了 3 份文档的关系：

备选架构设计文档和详细架构设计文档如何写已经在架构实战营详细讲过，详细架构设计文档的模板可以参考：详细架构设计文档模板。本文主要是给出方案设计文档模板供大家参考。

关于项目开发阶段如何划分以及要完成什么样的文档，不同的公司有不同的做法，以我亲自经历的三个典型做法来进行说明：

1）菊花厂：标准的软件工程瀑布流程做法，分为概要设计和详细设计两个阶段，与之对应的是概要设计文档和详细设计文档。从实践的经验来看，这种做法效率不高，概要设计和详细设计的边界不明确，经常出现为了文档而文档，为了流程而流程。

2）松鼠厂：只有简单的方案设计文档，内容主要包括接口设计和存储设计，基本没有代码级别的类设计和逻辑设计。从实践的经验来看，这种做法效率高，适合创业公司和小团队快速迭代，缺点就是一旦团队稍微大了后，因为代码设计和逻辑都没有经过评审，每个人都是基于自己的理解去添加修改代码，一段时间后，整个代码可能就比较混乱，难以理解，没有人知道代码的全貌和各种细节。

3）蚂蚁厂：设计阶段没有严格区分概要设计和详细设计，一般都是多个业务子域的多个技术负责人一起讨论好接口，然后各个应用自己来写“系统分析设计文档”（简称“系分”），系分文档包括：接口设计、兼容性分析、部署设计、关键流程设计等。从实践经验来看，这种做法能够兼顾效率和效果，因此本文的模板也以这种做法为标准。

本文用的专业术语是“方案设计文档”，这个名称在不同的公司有不同叫法，例如“项目设计文档”、“系统设计文档”、“概要设计文档”等，也没有哪个文档名称是业界标准，我们只需要知道这个文档是用来指导开发人员完成具体的开发即可。

具体模板内容如下。

前言

[可选，用于总体上描述本篇文档的内容和目的，一般包括项目名称（或者需求名称）、应用名称，目的一般都是“开发、测试、部署”]

[样例]

本文是扫码支付项目中会员域认证微服务的方案设计文档，用于指导认证微服务后续的开发、测试和部署。

修订历史

[可选，文档会因为各种原因导致修订，通过修订历史来记录变更情况]

[样例，因 infoq 写作平台不支持插入表格，这里用图片代替，实际 word 文档请用表格]

词汇表

[可选，用于明确定义和说明一些英文缩写、术语等，请用表格来呈现，infoq 写作平台不支持表格，所以只能一个一个的列，实际 word 文档请用表格]

[样例]

Reactor: 网络编程模式

Netty: 开源的网络编程框架

1. 项目背景

[必选，概要的介绍项目背景，一般可以从立项文档、会议纪要、架构设计文档中找到资料进行提炼，提炼的核心内容可以用 5W 模型（who、when、where、why、what）来写。更详细的信息可以直接贴需求文档、项目立项文档等链接]

[样例]

香港地铁公司（who）为了方便广大市民出行（why），准备在 2021 年（when）实现手机扫码乘车的功能（what），一期项目计划在 XX 线试点（where）。详细的项目背景信息请参考：XXXXX项目立项文档。

2. 总体设计

[必选，概要介绍一下全流程的架构设计，如果架构有变化就需要介绍架构的变化，包括 Role、Relation；不管架构是否有变化，都要介绍一下需求的全流程的实现逻辑（对应 4R 架构定义的 Rule）。更详细的信息可以直接贴链接。]

[样例]

扫码支付的完整流程如下，详细请参考：扫码支付架构设计文档。

3. 系统设计

系统设计就是指单个应用自己的设计。

3.1 系统边界

[必选，描述为了实现需求，自己负责的应用与外部哪些应用有关联（relation），这些关联可能是直接的接口访问、也可能是通过消息队列发送消息等方式，可以用架构设计中的“系统边界黑盒图”来展现边界和关联]

[样例]

订单中心本次项目开发依赖如下关联系统：

接口中心：需要接口中心提供 XXX 接口。

会员中心：需要提供 XXX 接口给会员中心调用。

促销中心：订单中心发送 kafka 消息给促销中心，异步通知促销中心进行个性化推荐。

……（以下省略，具体的依赖关系可以描述更详细一些）

3.2 接口设计

3.2.1 会员中心交互接口

3.2.1.1 接口流程

[必选，描述自己的系统内部接口的处理逻辑，一般用 UML 的 sequence diagram 展示，用文字描述处理步骤的具体处理逻辑。]

3.2.1.2 接口输入

[必选，用表格的形式描述输入参数和要求]

3.2.1.3 接口输出

[必选，用表格的形式描述返回数据，重点是错误码，需要一一列举，并且说明含义]

3.2.1.4 关键设计

[可选，如果接口处理流程中有一些关键的设计，例如全局幂等、限流、算法、兼容旧接口、熔断等，需要在这里特别描述，注意不要把关键设计放到接口流程里面讲，因为那样会导致不同的关注点混杂在一起，不方便阅读和理解]

3.2.1.5 接口要求

[必选，估算接口的性能要求、响应时间要求、请求量等]

3.2.1.6 接口依赖

[必选，用表格形式列出接口处理流程中依赖的其它系统的接口、前置条件等。]

3.2.2 促销中心交互接口

……（略）

3.3 逻辑设计

[必选，逻辑设计其实就是指导如何写代码的，如果是 Java 这种面向对象设计，那就是类设计；如果用了 DDD 之类的方法，那就是领域对象设计；如果是 golang 这种，那就是 goroutine 和 channel 这种设计。

注意这里不是写伪代码，而是写代码的设计思路。

为什么要单独拿出逻辑设计来写，而不是放在接口设计里面写呢？因为逻辑设计是给很多接口用的，不能放在某个接口里面写。]

3.4 存储设计

[可选，描述存储系统的数据结构如何设计，例如 MySQL 的表设计、Redis 的 key 设计，Elasticsearch 的 index 设计等。

为什么要单独将存储设计独立出来，而不是放在接口设计里面呢？原因和“逻辑设计”是一样的。]

3.5 其它设计

[可选，包括特殊的网络设计、安全设计、证书设计、工具设计等。]

4. 部署设计

4.1 部署流程

[可选，部署的方式和步骤，方式包括金丝雀发布、灰度发布、蓝绿发布等，步骤包括准备工作、执行步骤、验证操作等，如果公司的基建比较完善，可以做到自动化，那么这部分可以简单描述。]

4.1.1 准备工作

4.1.2 执行步骤

4.1.3 部署验证

4.2 回滚流程

4.2.1 回滚标准

[可选，描述在什么情况下要进行回滚]

4.2.2 回滚操作

4.2.3 回滚验证

5. 风险评估

[可选，常见的风险有：

技术风险，例如引入了某个新技术，还不熟悉；

项目风险：人员不熟悉，人员变动大；

外部风险：政策风险、业务变动、外部配合进度等。]

5.1 疫情风险评估

5.1.1 风险评估

5.1.2 应对策略