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

版本日期修订人描述
V1.02024/12/6nick 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)处理时间长无须用户现场等待
异常情况告警影响业务的关键功能运行不正常或数据不正常,是否需要告警通知(短信通知、消息通知、电话通知)
异常情况降级影响业务的关键功能运行不正常时,我们是否需做热下线或服务降级
审计是否需要关键业务操作的审计日志,以便回溯、举证

随时补充,欢迎关注(你也可在评论区补充哦!)

最后

小弟不才,学识有限,如有错漏,欢迎指正哈。
如果本文对你有帮助,记得“一键三连”(“点赞”、“评论”、“收藏”)哦!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/web/62276.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

电阻计RM3544、RM3545的使用

目录: 一、电阻计与PC通讯 1、硬件连接 2、RmLogger.exe的使用 二、RM3545测量35uΩ电阻 一、电阻计与PC通讯 1、硬件连接 可以设置USB或COM口(串口)连接PC,也可以设置为“打印”输出。 1)使用USB连接PC 2)使用串口连接PC …

Jenkins 的HTTP Request 插件为什么不能配置Basic认证了

本篇遇到的问题 还是因为Jenkins需要及其所在的OS需要升级,升级策略是在一台新服务器上安装和配置最新版本的Jenkins, 当前的最新版本是: 2.479.2 LTS。 如果需要这个版本的话可以在官方站点下载,也可以到如下地址下载&#xff1…

uniapp 封装自定义头部导航栏

封装原因 项目中有时候需要使用自定义的头部导航栏,原生的无法满足需求 参数 属性名描述示例title标题字符串:首页bgColor背景色字符串:#ffftype左侧的操作内容字符串:all,详细值请在下方查看 参数解释 type all…

docker学习笔记(五)--docker-compose

文章目录 常用命令docker-compose是什么yml配置指令详解versionservicesimagebuildcommandportsvolumesdepends_on docker-compose.yml文件编写 常用命令 命令说明docker-compose up启动所有docker-compose服务,通常加上-d选项,让其运行在后台docker-co…

Linux中inode

磁盘的空间管理 如何对磁盘空间进行管理? 假设在一块大小为500G的磁盘中,500*1024*1024524288000KB。在磁盘中,扇区是磁盘的基本单位(一般大小为512byte),而文件系统访问磁盘的基本单位是4KB,因…

5G扬帆乘劲风,遨游通讯赋能千行百业谱新篇

在大型工厂,轻触手机屏幕,实时库存数据、人员定位等信息便跃然眼前、一目了然;在边远油田,动动手指,即可实时查询设备温度、危险气体浓度等信息,大数据瞬间尽在“掌”握……在遨游5G防爆智能手机的助力下&a…

RT Thread Studio新建STM32F407IG工程文件编译提示错误

编译提示错误 原因: RT 源码使用4.0.3的话,请用STM32F4支持包的0.2.2版本,就不会出错了。 如果支持包用0.2.3版本的话,需要用RT内核4.1.0版本。0.2.3 版本更新了一些针对内核4.1.0的驱动代码,这几个定义都是4.1.0里的。

学生管理系统(java)

1.前期准备 (1)新建java项目 (2)新建java软件包以及三个文件Student.java,Student.txt,StuSystem.java Student.java package student_management_system;public class Student {private String id;private String name;private…

JavaWeb学习(2)(Cookie原理(超详细)、HTTP无状态)

目录 一、HTTP无状态。 (1)"记住我"? (2)HTTP无状态。 (3)信息存储客户端中。如何处理? 1、loaclStorage与sessionStorage。 2、Cookie。 二、Cookie。 (1&…

SpringBoot教程(三十二) SpringBoot集成Skywalking链路跟踪

SpringBoot教程(三十二) | SpringBoot集成Skywalking链路跟踪 一、Skywalking是什么?二、Skywalking与JDK版本的对应关系三、Skywalking下载四、Skywalking 数据存储五、Skywalking 的启动六、部署探针 前提: Agents 8.9.0 放入 …

flask创建templates目录存放html文件

首先,创建flask项目,在pycharm中File --> New Project,选择Flask项目。 然后,在某一目录下,新建名为templates的文件夹,这时会是一个普通的文件夹。 然后右击templates文件夹,选择Unmark as …

Java进阶(注解,设计模式,对象克隆)

Java进阶(注解,设计模式,对象克隆) 一. 注解 1.1 什么是注解 java中注解(Annotation),又称java标注,是一种特殊的注释 可以添加在包,类,成员变量,方法,参数等内容上 注解会随同…

部署loki,grafana 以及springcloud用法举例

文章目录 场景docker 部署grafanadocker-compose部署loki维护配置文件 local-config.yaml维护docker-compose.yml配置启动 grafana 添加loki数据源springcloud用法举例查看loki的explore,查看日志 场景 小公司缺少运维岗位,需要研发自己部署日志系统,elk…

keil报错---connection refused due to device mismatch

解决办法如下: 记得改成1 把Enable取消

第三节、电机定速转动【51单片机-TB6600驱动器-步进电机教程】

摘要:本节介绍用定时器定时的方式,精准控制脉冲时间,从而控制步进电机速度 一、计算过程 1.1 电机每一步的角速度等于走这一步所花费的时间,走一步角度等于步距角,走一步的时间等于一个脉冲的时间 w s t e p t … ……

vue中pdf.js的使用,包括pdf显示,跳转指定页面,高亮关键词

目录 一、下载pdf.js 二、引入到本地的项目中 三、实现预览pdf 四、跳转到指定页面 五、利用pdf里面的find查找关键词 六、修改页面大小为实际大小 一、下载pdf.js https://github.com/mozilla/pdf.js 里面有很多的版本, 高版本的可能浏览器不兼容或者还要考…

OD B卷【连续字母长度】

题目 给定一个字符串,只包含大写字母,求在包含同一字母的子串中,长度第k长的子串的长度,相同字母只取最长的那个子串。 输入描述: 第一行输入一个子串(长【1,100】),只包含大写字母…

python中的 Pydantic 框架介绍

Pydantic 框架介绍 Pydantic 是一个用于数据验证和设置管理的 Python 库。它主要通过数据模型类的定义来处理 JSON 数据、解析请求和响应数据,并提供自动化的验证和转换。Pydantic 主要用于处理 Python 类型的安全性和验证,尤其在 FastAPI 等现代 Pytho…

桥接模式和组合模式的区别

桥接模式(Bridge Pattern)和组合模式(Composite Pattern)都是结构型设计模式,旨在解决对象结构的复杂性问题,但它们的应用场景和目的有所不同。以下是它们的区别: 1. 定义与目的 桥接模式&…

Qt 小项目 学生管理信息系统

主要是对数据库的增删查改的操作 登录/注册界面: 主页面: 添加信息: 删除信息: 删除第一行(支持多行删除) 需求分析: 用QT实现一个学生管理信息系统,数据库为MySQL 要求&#xf…