【提升效率】如何写好一份详细设计文档

版本	日期	修订人	描述
V1.0	2024/12/6	nick huang	创建文档

背景

CSDN在发起“如何做好一份技术文档”的活动。
想起我最近在写一份详细设计，有一些感受：

一份考虑较周全的“详细设计文档模板”能起到质量保底的作用。
当一名初级技术人员需要编写详细设计文档，如果有一份较全面的详细设计文档模板能够担当指引：
1、有助于帮忙技术人员考虑到一些容易遗漏的点
2、有助于帮忙技术人员编写出可读性较高的文档

详细设计文档的一些重要因素（我认为的）

需求背景（必需）

文档的开始，要阐述这份设计对应的需求。

至少阐述这几个问题：
1、帮用户解决什么问题（用户痛点）

最好能阐述这几个问题：
1、我们将打算如何修改
2、修改这几个点对应哪几个系统的哪几个功能（最好能用功能菜单来描述，避免大家理解不一致）

如果需求背景比较简单，可以自己直接阐述；
如果比较复杂，可以制作“文档链接”，确保在“评审时”能一键跳转到《需求文档》中继续介绍，观众无须过多等待。

需求细节快链（建议）

Tips
除了上述的宏观的“需求背景”。
在详细设计评审会议上讲述具体某个细节的实现方式时，为了帮助观众能快速地回顾该需求细节。
我通常会在描述实现细节的下文，放一张“需求文档针对该需求的缩小版截图”。
讲解时，快速放大截图帮助观众快速地回顾该需求细节。

方案描述（必需）

详细介绍如何实现需求文档的各个需求点（建议拆分功能点描述）。
有逻辑性地描述我们的方案如何最终实现用户需求。

比如：有一个需求，在Apple页面上新增Boy字段，默认为Cat值，支持更新，更新时给Dog用户发送一封通知邮件。
那么，我们可以如何描述。

1、修改/createApple接口
修改逻辑：
1）新增Boy字段以及关联的ORM
2）新建逻辑中，设置Boy字段默认值为Cat

2、修改/updateApple接口
1）入参添加Boy字段
2）添加Boy字段的更新逻辑
3）更新时给Dog用户发送一封通知邮件的实现逻辑

3、修改/getApple接口
1）接口出参添加Boy字段

上述，是通过“ 如何写数 → 如何使用数据 ”的逻辑阐述如何逐步实现用户功能。

过程中有一些细节问题，可能产品未提及，可主动跟产品确认，比如：
1、新增Boy字段，默认为Cat值。可跟产品了解：Cat值后续改动的概率，如概率大，做成热配置，降低修改成本
2、Boy字段的更新逻辑。跟产品沟通：是否需支持多用户并行更新同一行记录？如需，则详述我们如何处理
3、发送一封通知邮件。跟产品沟通：如果邮件发送失败，是否影响更新数据落库？如不应影响，我们阐述如何实现异步，以及如何实现发送失败的补偿发送

Tips
复杂的写数逻辑或算法可通过下述途径，让观众更容易理解：
1）伪代码、伪SQL代码
2）时序图
3）流程图

通过合适的技术手段讲解实现方式

通过合适的技术手段讲解实现方式，有哪些典型的场景呢？

接口涉及多组件或多应用，可用“时序图”可视化地表达（如涉及，必需）

用户访问/apple接口访问boy应用，然后boy应用通过访问/cat接口访问dog应用，dog应用将数据保持在MySQL的fish表，再将数据写入Redis，最后调用邮件平台发送一封邮件，再将fish表的id字段沿着请求的各节点返回给用户。

上面一大段文档，枯燥可读性差、容易造成理解不一致。
如果用时序图表达，情况将有所改善：
在这里插入图片描述

Tips
上面的时序图，毕竟要画图，你可能觉得很麻烦，工作量较大。
这里推荐一个工具——PlantUML。
通过写代码的方式画时序图。
比如上图，它的画图代码如下，你可以用PlantUML Web Server试下：

@startuml
用户 -> boy应用 : /apple
boy应用 -> dog应用 : /catdog应用 -> MySQL : fish表
MySQL --> dog应用 : fish.id=xdog应用 -> Redis
Redis --> dog应用dog应用 -> 邮件平台: 发送邮件
邮件平台 --> dog应用: 成功/失败dog应用 --> boy应用 : fish.id=x
boy应用 --> 用户 : fish.id=x@enduml

数据库表设计与写数规则（如涉及，必需）

如果实现涉及数据库表结构的新增或字段变更，请务必描述出来。

数据库单表设计点描述的一些重点：
1、常规的元素要设计好，比如：字段名、字段注释、主键、表注释
2、字段类型要考虑长度、精度
3、如新增字段涉及枚举，各枚举值（或数据字典）要罗列好，后续开发人员可拿到即用
4、如果写数规则较复杂，可以用表格（如Excel）的形式来描述各字段的写数示例，大家更容易理解
在这里插入图片描述

数据库表关系描述的一些重点：
1、使用“ER图”表示表与表之间的关系（至于ER图的绘制，我会用DRAW.IO或EZDML，目前没有特别倾向的绘图工具，欢迎推荐）
在这里插入图片描述

涉及接口要罗列出来（如涉及，必需）

修改某个功能，涉及需要修改或新增的接口，都要罗列出来。

1、如果新增接口，描述接口的信息要齐全：
1）URL
2）Method
3）入参
4）出参
5）权限要求（这点容易遗漏哦！）
6）接口描述
可以借助Swagger等组件描述，但要注意能一键链接到位。

2、如果修改接口，要高亮出其中修改点或分点结构化文字描述。
如果修改接口，建议：
1、高亮出其中修改点
2、或者，分点文字描述其中的修改点

避免阅读人员需通篇阅读接口文档，加之各种对比手段，才能获知我们的修改点（还可能识别遗漏）。

Checklist 检查清单

针对不同的需求，需要设计的重点可能不同，以下Checklist的点可能可以参考：

维度	解析
接口性能	接口的响应时间是否达到要求
业务吞吐量	需支持单位时间的接口访问量
权限校验	接口权限校验、数据权限校验
数据校验	入参校验、业务规则校验、状态校验
幂等校验	接口支持相同数据重复调用，不会产生错误数据
数据一致性	设计多个数据库写数动作或多个远程调用，考虑使用本地事务或分布式事务
同一数据的强一致性	多人对同一笔数据同时操作，使用乐观锁或悲观锁确保符合用户的操作预期
异步处理	哪些业务动作需异步处理（要注意失败通知、失败补偿等场景），以达到：1）故障时不影响主流程；2）处理时间长无须用户现场等待
异常情况告警	影响业务的关键功能运行不正常或数据不正常，是否需要告警通知（短信通知、消息通知、电话通知）
异常情况降级	影响业务的关键功能运行不正常时，我们是否需做热下线或服务降级
审计	是否需要关键业务操作的审计日志，以便回溯、举证