编写本规范的出发点

1. 在一个公司里面，没有一定的规范去编写文档，会导致每个同学都按照自己的思路写，最后在评审方案的时候，会理解起来比较困难。
2. 每个人按照自己的思路的时候，因为每个人的能力差异，最后可能考虑的方案严谨上做的不够，导致方案上线出现各种问题。
3. 所以通过结构化的方式来约束研发同学，一方面让大家按照相同的思路来去思考方案。一方面从结构上约束大家按照严谨的思路来思考。这样最后做出来的方案整体上都会比较一致
4. 文档中的图文工具尽可能使用 文本绘图/画板 功能解决，方便后续同学在此基础上继续维护。PlantUML语法参考：plantuml.com/zh/

背景&目的

这部分主要说清楚

1. 为什么要做这件事情，核心要解决的问题
2. 要达到的目的是什么

概要设计

业务模型

业务模型是对需求进行的抽象，因为只有抽象才能设计稳定的架构，支撑上层多变的业务诉求，

业务模型核心抽象两个东西：

1. 概念
2. 流程：流程是对概念的串联

业务模型建模完之后，还需要在进行推演，看是否能支撑需求对应的业务细节

业务流程

这部分重点说清楚，在业务层面的流程是什么样子的，能全面的了解清楚业务逻辑

这部分一般会引用产品prd中的业务流程

技术架构

1. 这部分用架构框架来说清楚，是新增加一个什么样的架构，还是在已有的架构上面增加一个模块，还是修改一个模块，以及为什么要这么做，解决什么问题。
2. 框架一般来说是分层架构的，下层给上层提供能力。上层会调用下层的多个能力

比如：

应用架构

这部分主要说明应用之间的依赖关系，确保不要造成应用之间的依赖混乱。

比如：

部署架构

这部分说清楚应用是如何部署的，是单机，多机，单机放还是多机房。有状态，还是无状态，发布是否有需要注意的一些地方。

比如：

对于具体案例，也可以在网上搜索查看。

详细设计

用例

用例核心讲清楚，系统有哪些角色，每个角色有什么功能，因为接下来的业务流程里面核心讲的就是每个功能的流程的细节是什么样的。

比如：

数据模型

这部分说清楚数据表结构的设计，有什么实体，实体之间的关系。

数据模型不是对业务模型的一一映射，两者会有关系，但是没有强相关的关系

比如：

表结构设计

这部分主要说明每张表的具体详细设计，表结构是什么样的，索引是什么样的。

比如：

表名：saas_app

索引：

唯一索引：uk_app_id(app_id)

字段名

类型

说明

id

数据库自增id

create_time

datetime

update_time

datetime

deleted

int

app_id

varchar

应用唯一id

cn_name

varchar

应用中文名称

...

业务流程

1. 这部分要非常详细的说清楚用例中的每个功能的逻辑，以及在每个逻辑设计的时候需要注意的地方，设计的细节。接下来的编码环节就是根据这个业务逻辑进行的实现
2. 这部分的细节说明，主要是用序列图，但是也不一定，不管用什么样的图形，都是手段，核心的目的还是为了说清楚具体的逻辑实现

流程1

这里核心的是用UML中的时序图，流程图等等，把流程的细节讲清楚，至于用什么图不重要。重要的事把逻辑细节讲清楚

一些细节的说明：

比如：缓存的设计，需要注意的地方，依赖那些接口

注意：这里需要说清楚一下，公有云和私有云差别点

流程2

流程3

接口

这部分主要是说清楚该方案文档中对应的接口，入参，出参，以及调用上需要注意的地方

web接口

web接口1

web接口2

dubbo接口

dubbo接口1

dubbo接口1

MQ

这里记录下来每个环境中mq的内容，topic，msgType，tag等等。以及消费，发布的时候需要注意的地方

稳定性

这部分非常重要，但是经常在评审和上线的时候没有重点关注起来，导致上线之后出现各种问题，而且出现之后我们不能及时的知道。

所以需要在方案阶段就需要详细的考虑起来

数据一致性

对于数据一致性主要是因为数据可能会在多个系统中存在，需要说清楚如何保障一致性，如果出现了一致性，那么应该怎么做。如何对不一致的数据进行监控

比如：

1. 通过事务来保障一致性
2. 如果不能用事务，那么一致性脚本比对是否可以比对出来，和进行修正

异常监控&告警

新功能和迭代上去之后

1. 监控哪些指标（有业务指标，系统指标，错误指标等等）
2. 如何监控
3. 如何告警
4. 当出现问题之后如何能快速恢复和修正

资损防控

这部分主要在有业务中涉及到资金往来的业务的时候需要增加。

资损防控主要原因是如下几方面：（本质上是因为数据在不同系统中流转，每增加一个处理节点，就会增加一次数据的不一致性，所以需要进行资损防控）

1. 费用的配置需要在多个系统中流转
2. 费用的计费拆分也是在多个系统中流转

对于资损防控做法上可能会有多种，数据比对等等。

性能

这部分主要是说清楚两块内容：

1. 此次技术方案可能涉及到的性能瓶颈点
2. 对于每个性能瓶颈点，压测方案，如何提升

比如：

1. 某个流程中的某个细节点可能在流量大的时候成为瓶颈。
2. 缓存redis，数据库表等可能会出现性能瓶颈等等

性能点1

性能点2

发布计划

这部分主要说清楚，发布的时候需要做的事情（按照顺序来记录），确保发布没有遗漏和顺序正确。核心包含几部分

1. 配置项
2. 数据库脚本
3. 应用依赖关系

在具体做的时候，每一项做完之后都会在这里记录一下

项目时间

这里主要记录项目的事项，每个事项的参与人，时间段，里程碑。