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

  • 产品部分
    • 需求和业务场景
    • 当前系统/对比系统
  • 静态部分
    • 模块
    • 业务实体
      • 定义
      • 生命周期
    • 设计实体
  • 动态部分
    • 服务调用
    • 核心场景实现
    • 技术难点解决
  • 工程部分
    • 分工
    • 排期
  • 文档部分
  • 延展阅读/参考

产品部分

需求和业务场景

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

用例图sample

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

当前系统/对比系统

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

静态部分

模块

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

系统功能蓝图sample2

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

业务实体

定义

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

实体关系图Sample

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

生命周期

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

状态机图sample

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

状态机图sample2

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

设计实体

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

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

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

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

表图sample

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

动态部分

服务调用

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

(作者注:这个图暂时没有标准,一般期望说清楚调用关系、系统使用的组件、系统的层次)

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

系统架构图sample3系统架构图sample2系统架构图sample1

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

核心场景实现

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

时序图sample

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

流程图sample

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

技术难点解决

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

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

twitter缓存设计

https://timyang.net/architecture/twitter-cache-architecture/

工程部分

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

分工

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

排期

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

项目进展图sample2项目进展图sample

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

文档部分

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

这里有一些tips:

  • 所有专有词汇,注意中英文
  • 对于自创设计图,加上必要的图例
  • 结构化的文案比小说更容易快速阅读
  • 图中所有的元素,对齐比不对齐更好,优先用细长型线条,同类型元素应大小风格一致
  • 所有设计图应该附上附件,用于后续更新
  • 文档的目的为了说明系统,但不等同于系统所有细节,所以应该是系统的抽象,帮助别人在不看代码的情况下了解清楚系统的全貌
  • 对于一个不大的系统,相比画出其所有可以画的UML图,我们建议只描述其核心部分,因为一旦某个系统小到一定程度,就无需解释
  • 底层数据model是关键,90%的业务系统,一旦知晓底层model,有经验的开发应该可以推断其上层服务

延展阅读/参考

Advertisements
This entry was posted in Photograph and tagged , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s