如何文档化一个业务需求的设计与实现

产品部分

需求和业务场景

当前系统/对比系统

静态部分

定义

生命周期

模块

业务实体

设计实体

动态部分

服务调用

核心场景实现

技术难点解决

工程部分

分工

排期

文档部分

延展阅读/参考

1，产品部分

需求和业务场景

实现一个需求之前必须对需求边界、场景、模块界定清楚，最忌讳遗漏需求。分析清楚需求后，可以产出的是用例图（Usecase Diagram），分别对不同角色可以用当前系统做什么进行说明。

（https://www.uml-diagrams.org/examples/online-shopping-use-case-diagram-example.html?context=uc-examples）

当前系统/对比系统

我们在做一些需求时候，很可能已经存在一些现有系统，我们需要的是在现有系统上进行添加/改造/升级/迁移等，或者存在类似系统，在此文档中可以进行说明。

2，静态部分

模块

一个系统如果相对较大，或者其中有清晰的划分和聚合，一般建议拆分模块，对于不同模块就可以归属到不同人负责，实现并行开发。这里可以产出是业务模块图 / 子系统图 / 系统功能图蓝图。

（https://36kr.com/p/5105245.html）

业务实体

定义

业务实体是业务系统中比较重要的基础概念，譬如我们在设计服务包系统时候，服务、服务包就是很重要的业务实体，一个服务包可以包含多个服务，一个服务也可以被包含在多个服务包中。这里一般使用实体关系图（ERD）表达出实体与实体之间的关系。

（https://www.lucidchart.com/pages/er-diagrams）

生命周期

对于核心的业务实体，我们比较关心其生命周期和状态流转，服务包可以创建、上线、下线，所以我们很容易得到服务包的生命周期，使用状态迁移图（STD）/ 状态机图（State Machine Diagram）表现。

（https://www.lucidchart.com/pages/uml-state-machine-diagram）

（https://cloud.smartdraw.com/editor.aspx?templateId=0853040f-1b78-413a-b9d9-bc8e2acd3abe）

设计实体

设计实体是相比较业务实体而言的，一般而言，设计实体是为了实现系统和业务实体存储而设计出来的实体，最终对应的就是系统的存储。如上提到，服务和服务包之前是多对多关系，那么通常这里就会做一张关联表存储，所以设计实体就有：服务表、服务包表、服务包和服务的关联表。

再具体一点的细节还需要考虑：设计实体的逻辑删除、物理删除、业务状态如何设计或者是否需要，如果条件允许，尽量不要将逻辑删除和实体状态关联在一起。

对于一个较大的业务实体，也可以拆分成多个设计实体，譬如服务包合同是一个业务实体，但是真实存储时候，我们将其拆成：母合同、服务子合同等。

设计实体是整个需求实现、系统实现的基石，一旦此处清楚，解释其他上层调用、外部关系都会轻松和简单。表现设计实体最简单方式就是表图（Table Diagram），对于设计文档，建议按模块分别表现出表的核心属性和关系，非常细节的字段可以放在建表SQL Script中。

（https://www.lucidchart.com/pages/database-diagram/database-design）

3，动态部分

服务调用

我们的系统现在大都基于微服务，前后端分离，后端服务分层，所以对于系统需要用系统架构图（Architecture Diagram）。

（作者注：这个图暂时没有标准，一般期望说清楚调用关系、系统使用的组件、系统的层次）

系统架构图是从系统维度去查看系统的实现和技术使用。

（https://www.edrawsoft.com/architecture-diagram.php）

核心场景实现

任何一个系统/需求，必然有核心需求和关键场景，对于这些的实现，如果存在一定tricky的地方，可以对此详细说明，可以采用的是图是时序图（Sequence Diagram）或者流程图（Flowchart）。

（https://cloud.smartdraw.com/editor.aspx?templateId=44c95db6-9408-4d0f-a218-cb43cbdd07fd）

（https://www.lucidchart.com/pages/what-is-a-flowchart-tutorial）

技术难点解决

系统中也会遇到一些比较麻烦的地方，如缓存/消息/异步调用/高并发/分布式数据一致性等，对于这些技术维度的难点，可以拎出来单独讲解。

除了上述提到的所有图，还有其他UML图可以试用，所有的目的都是为了说明清楚系统的设计和实现。

（https://timyang.net/architecture/twitter-cache-architecture/ 此为twitter的缓存设计图）

4，工程部分

这里介绍的工程部分，和系统设计无关，但是可以作为迭代开发的子文档。

分工

按照上述，一旦分了模块，就可以将具体模块分配到个人。

排期

确定关键事件节点，作为项目自我管理的参照。

（https://www.lucidchart.com/blog/gantt-chart-alternatives）

5，文档部分

作为一个开发工程师，大部分人会忽略文档的描述和严谨。对于一个有追求的Dev，应该花一定时间在文档的编写上，注意自己的专业术语和设计图，原则上讲不该随意地画各类图，而应尽可能简单、清晰地描述。

这里有一些tips：

所有专有词汇，注意中英文

对于自创设计图，加上必要的图例

结构化的文案比小说更容易快速阅读

图中所有的元素，对齐比不对齐更好，优先用细长型线条，同类型元素应大小风格一致

所有设计图应该附上附件，用于后续更新

文档的目的为了说明系统，但不等同于系统所有细节，所以应该是系统的抽象，帮助别人在不看代码的情况下了解清楚系统的全貌

对于一个不大的系统，相比画出其所有可以画的UML图，我们建议只描述其核心部分，因为一旦某个系统小到一定程度，就无需解释

底层数据model是关键，90%的业务系统，一旦知晓底层model，有经验的开发应该可以推断其上层服务

6，延展阅读/参考

浅谈互联网业务系统设计规范

https://www.jianshu.com/p/98b8c97e2ce1

Java各种系统架构图及其简介

http://www.cnblogs.com/zjoch/p/6404377.html

一图胜千言——软件开发中的形象思维与图的运用

http://www.uml.org.cn/UMLForum/200903302.asp

UML Tutorial

https://www.tutorialspoint.com/uml/index.htm

从 0 到 1 教你设计业务系统

https://36kr.com/p/5105245.html