系分设计——技术人的必修课

前言：笔者以技术方案设计规范的角度，和大家分享互联网公司内如何要求技术同学撰写系分设计文档。系分设计非常锻炼开发者的技术思维，有意地训练可以提高技术素养。

什么是系分设计文档

系分设计（系统分析设计）是阿里巴巴公司内部开发线在PRD转开发方案时撰写的技术文档。几乎每个团队在技术迭代前都会使用系分设计文档在团队内部开展方案评审，是开发工程师的基本功之一。系分文档依赖VP（visual paradigm）等UML工具进行创作，通过各种UML图和少量的文字说明来呈现技术方案在实现上的每一个细节。

系分设计的要求较高，需要撰写者提前在脑海中完成代码的落地，并且需要撰写到一个懵懂的开发者对着文档也能完成开发的程度。有些工作要分给新同事甚至外包去做，那么写到这种程度是必须的。本文就笔者书写系分设计文档的经验，与大家分享如何写成一篇系分设计文档。

系分设计的文章构成

一般系分设计文档分成5个部分，包括需求背景、设计思路、方案设计、非功能性说明、变更部署说明、排期计划。

1 需求背景

设计背景是系分设计的第一个部分。要求撰写者简要描述一下功能需求的目标和价值，并附上相关的所有文档，比如需求文档、PRD设计文档等。

这部分的作用主要是描述工作开展的价值，并收集之前的所有文档，后续相关人员只需要在这里查询文档就可以了。如果系分评审时有不了解需求背景的技术同学在场时，可能需要解释一下需求实现的价值。

2 设计思路

设计思路没有固定的格式要求，主要是要把技术方案实现的想法讲清楚。这部分内容可长可短，简单的需求可能一笔带过，复杂的需求可能比方案设计还要长。

设计思路的撰写要表达两个内容：
一是给各位评审同学简要讲解一下PRD的内容，同在场的需求方和产品经理明确一下，文档对PRD的理解没有偏差；
二是给评审的技术同学讲一下实现思路，如果后面的方案设计比较复杂或者比较抽象，需要提前讲解一下选择这个方案目的、优势和预期的结果，那么就可能需要详细展开描述，甚至使用一些活动图、时序图、流程图等，把用户的交互逻辑给大家说明一下。如果没有特别的实现思路，那么也可以一笔带过。

设计思路里可能也涉及技术方案，但和下面的方案设计不太一样。设计思路里的技术方案更强调从用户使用的视角来描述方案，而下面的方案设计则更强调代码层面的实现。

3 方案设计

这里是方案设计的核心，需要撰写者将脑海中的代码整理成UML图的形式，也是对照文档完成开发的部分。这部分以图为主，文字说明较少，这里会使用用例图、类图、ER图、状态图、时序图、流程图等各种UML，从各个角度对关键实现完成描述。撰写时不用全部绘制，可依据需要，选择涉及到的UML即可。

用例图

用例图是第一个UML图，是最简单的图，也是必须要绘制的图，后面的UML图都是可选的。用例图描述了从用户、用户页面或外部系统来看，完成此需求，必须要实现的功能，以及页面展示功能入口的先后顺序。它对应了代码对外暴露的接口。

用例图是一个分水岭，这里的用例还是纯中文的描述，产品经理还是可以听懂的，后面的内容产品经理一般就不用听了。

（用例图示例）

类图

类图用来描述本次需求设计时的领域概念和概念间的关系。笔者很少选用类图，因为笔者是贫血模型坚定的支持者，如果描述数据结构，笔者更愿意使用ER图，如果描述方法关系，笔者更愿意使用组件图。

（类图示例 [来自网络，侵删]）

ER图

ER图是用来描述本次需求新增的数据模型、数据属性，以及和已有数据模型间的关系。对应表模型设计和数据持久化层的SQL实现。如果涉及到字段的枚举，那么还要将枚举定义描述出来。

（ER图示例）

状态图

状态图承继ER图或类图的设计，主要对运行过程中数据的有限状态机的描述。包括起始是什么状态，终了是什么状态，一共有多少种状态，哪些指令会导致状态转换到下一个状态。这里状态对应ER图的状态枚举字段，指令对应代码中需要实现的底层接口。

（状态图示例）

时序图

时序图是从应用运行的角度，描述用户、本应用的重要模块和外部应用之间的交互细节和顺序，以及初始化或预处理时的步骤。一般时序图会对应用例图中重要的用例。时序图的目的是要描述，核心功能是如何完成运转的，每一个接口要完成什么样的调用顺序、要给外部应用什么样的接口逻辑。

（时序图示例）

组件图

组件图是从代码工程角度，从数据库和外部系统向上到暴露到API，自下而上地描述代码工程中有哪些类，每个类需要提供什么样的接口，依赖哪些接口，各个组件接口的相互间依赖关系是什么。开发者仅需要对照类名和接口名，完成代码开发即可。组件图和时许图分别从不同角度描述技术细节，两者都是非常常用的UML图。

（组件图示例）

流程图

流程图是对组件图实现细节的进一步细化。流程图会选取组件图中的较为核心的几个接口，描述接口的实现细节。开发者对照流程图来完成核心代码的编写。

一般设计到流程图这一步，基本上所有的技术细节都可以表达清楚了。

（流程图示例）

部署图

系统图在绘制上非常类似组件图的绘制，但系统图强调对各个应用系统整体架构部署和对接上的的描述，而不是针对代码工程内部的描述。系统图往往用来描述应用与其他周边应用的影响关系，对于系统重大调整中涉及稳定性的部分，可能需要依靠此图来考虑。该部分更常出现在第三步的“非功能性说明”中。

（部署图示例）

3 非功能性说明

如果需求涉及到高可用、高并发、高安全等非功能性要求，或者设计的内容是系统重构或迁移，那么可能需要单开这一章节来论证之前的开发方案如何满足非功能性设计。这一部分不易过长，主要是相评审的各位技术同学描述对非功能性要求的考虑。

这里可能会设计到部署或系统架构图的绘制，着重强调非功能性问题的来源和影响。

4 变更部署说明

这里是对上线后代码如何发布，发布后如何应急响应的操作说明，包括著名的变更三板斧（可灰度、可监控、可应急）。这里也可以先留空，在开发过程中补充完善。

发布流程

这里主要描述发布过程中的动作，并提前准备好发布需要的配置和脚本。这里应描述到，发布时可以对照文档完成发布的程度。

灰度计划

这里描述发布上线后如何选择灰度的用户，相关配置的操作方法，以及灰度逐步放开的计划安排。

监控配置

这里描述发布上线后如何配置上线功能部分的监控，以及监测的指标。这里需要技术同学评审监控配置的有效性。

应急策略

这里描述已知的故障风险和应对措施。包括监控指标成什么样的状态时，表示什么样的故障已经发生，需要进行什么样的操作，例如回滚、切流、限流、重启等。这里需要技术同学评审监控配置的可操作性。

5 排期安排

这里是系分设计文档最后的部分，主要前端以及后端各个功能模块的实现排期安排和责任人。开发小组可以在日会上对照排期计划同步各自进展。

结束语

一般系分设计文档写到这种程度就差不多了。系分设计非常锻炼一个开发人员的技术素养，缺点是需要开发人员投入一定的精力专心写文档，可能会给敏捷开发的项目经理一种“怎么还不去开发”的错觉，由于前期思考的较为充分，所以虽然开发的起步较晚，但后续都是一马平川，即使有调整，交流起来也会很快。