前言笔者以技术方案设计规范的角度和大家分享互联网公司内如何要求技术同学撰写系分设计文档。系分设计非常锻炼开发者的技术思维有意地训练可以提高技术素养。什么是系分设计文档系分设计系统分析设计是阿里巴巴公司内部开发线在PRD转开发方案时撰写的技术文档。几乎每个团队在技术迭代前都会使用系分设计文档在团队内部开展方案评审是开发工程师的基本功之一。系分文档依赖VPvisual 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 排期安排这里是系分设计文档最后的部分主要前端以及后端各个功能模块的实现排期安排和责任人。开发小组可以在日会上对照排期计划同步各自进展。结束语一般系分设计文档写到这种程度就差不多了。系分设计非常锻炼一个开发人员的技术素养缺点是需要开发人员投入一定的精力专心写文档可能会给敏捷开发的项目经理一种“怎么还不去开发”的错觉由于前期思考的较为充分所以虽然开发的起步较晚但后续都是一马平川即使有调整交流起来也会很快。 系分设计——技术人的必修课
前言笔者以技术方案设计规范的角度和大家分享互联网公司内如何要求技术同学撰写系分设计文档。系分设计非常锻炼开发者的技术思维有意地训练可以提高技术素养。什么是系分设计文档系分设计系统分析设计是阿里巴巴公司内部开发线在PRD转开发方案时撰写的技术文档。几乎每个团队在技术迭代前都会使用系分设计文档在团队内部开展方案评审是开发工程师的基本功之一。系分文档依赖VPvisual 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 排期安排这里是系分设计文档最后的部分主要前端以及后端各个功能模块的实现排期安排和责任人。开发小组可以在日会上对照排期计划同步各自进展。结束语一般系分设计文档写到这种程度就差不多了。系分设计非常锻炼一个开发人员的技术素养缺点是需要开发人员投入一定的精力专心写文档可能会给敏捷开发的项目经理一种“怎么还不去开发”的错觉由于前期思考的较为充分所以虽然开发的起步较晚但后续都是一马平川即使有调整交流起来也会很快。