为什么要写技术文档?

技术设计文档

一、业务分析

1.1 业务背景

1.2 业务用例

1.3 业务流程

二、系统分析

2.1 系统架构

2.2 领域模型

2.3 系统用例

2.4 数据模型

2.5 状态机

2.6 数据流转

三、系统流程分析

3.1 外卖订购时序

3.1.1 时序图

3.1.2 幂等设计

3.1.3 并发设计

3.1.4 兼容性设计

3.1.5 风险点设计

3.2 xx流程

四、非功能性设计

4.1 可测性设计

4.2 性能分析

4.3 并发能力设计

4.4 容错能力

4.5 运维能力

五、数据分析

六、接口设计

6.1 查询接口

七、里程碑

为什么要写技术文档?

作为一名优秀的架构师，系统技术方案设计文档应该是必备技能。为什么要写设计文档呢，我觉得有以下几个好处：

全局设计抽象：文档可以让我们更好的整理思路，避免未经详细思考，直接编码，因为直接编码可能只看到了系统的一部分，会有很多的疏漏。文档是具有目录结构，比代码的抽象层次更高，可以让我们思考全局设计，思考整体的扩展性和复用性，以及后续系统整体的解决方案，设计的更合理。站在高处看，提供一张“全景图”，会有不一样的思考。
更好细节设计：相信各位技术同学，都遇到过直接上手编码，经常会出现考虑不周的情况，在详细的细节实现层面由于之前考虑不周，不得不返工，在文档编写的过程中，会考虑到整个系统流程，把细节思考到位；
沟通和交流：我们交付的是能够让被人理解以及后续可维护的功能，一般在写文档的过程中，会和团队成员一起交流，听听别人的意见和建议，进行思想的碰撞，更容易避免“踩坑”，进行更合理的设计。
沉淀技术资产：经常我们在接手新的系统或者功能的时候，会面临系统资料缺失，不能很好的上手，通过编写技术设计文档，也是一种技术传承，后续在进行功能修改的时候，我们要及时更新文档，让文档保鲜，这是作为技术人的一种责任；

技术设计文档

技术文档应该是更上层的抽象，那一份优秀的技术设计文档应该有哪些部分呢，个人感觉方案设计就是业务分析+系统分析，下面我就以用“户权限控制”这个小功能，来看下如何写一份技术文档

一、业务分析

1.1 业务背景

在做设计之前，首先需要知道业务背景是什么？需要把业务PRD深入理解，我觉得可以套用5W2H法则来看，下面是摘自与百度百科的介绍

（1）WHAT——是什么？目的是什么？做什么工作？

（2）WHY——为什么要做？可不可以不做？有没有替代方案？

（3）WHO——谁？由谁来做？

（4）WHEN——何时？什么时间做？什么时机最适宜？

（5）WHERE——何处？在哪里做？

（6）HOW ——怎么做？如何提高效率？如何实施？方法是什么？

（7）HOW MUCH——多少？做到什么程度？数量如何？质量水平如何？费用产出如何？

这里找了一篇比较完整的prd文档：PRD的标准写法一套全面文档规范（完整版带模板） | PM28

为什么要做这个需求？需求是核心解决了什么问题？期望什么时间上线？达成什么样的目标？

1.2 业务用例

一般会先分析当前功能会有几个使用角色，根据不同的角色分析对应的业务用例，也就是用户的操作功能。

1.3 业务流程

还是站在业务角度，站在用户使用角度，来分析一次事件的流程，一般一个需求会有很多业务流程，可以优先分析出主要的业务流程。

比如一个交易订单的处理流程：

一次办公用品申请流程

二、系统分析

2.1 系统架构

我觉得系统架构是以具体的业务分析为输入，以总体的企业应用架构为原则和规范为指导，得以实现具体的业务架构。

如果本次需求功能比较大，涉及很多系统的话，需要首先了解不同系统的功能和边界，分析到底该功能点定位是什么？需要放在哪个系统中？

下面是个示例图，一般会将整个大的流程，按照不同的域划分，有些是偏底层服务和数据，有些是

偏中台服务，一般沉淀通用的能力支撑更多的业务场景，再往上会是垂类业务系统，沉淀的更多是业务玩法，要熟悉整个系统之间的边界和关系，然后把本次的需求功能填充到合适的位置，也就是域架构师的职责。

2.2 领域模型

领域模型是对领域内的概念类或现实世界中对象的可视化表示。又称概念模型、领域对象模型、分析对象模型。它专注于分析问题领域本身，发掘重要的业务领域概念，并建立业务领域概念之间的关系。

简单来说，也就是对域进行划分，然后找出不同域之间的关系，领域划分大到整个企业，比如腾讯，可以分为社交、游戏、电商等板块，小到每个系统功能，比如一个系统分为协议、通知、任务等非常小的域，这个也是不同域架构师的不同职责范围。

画领域模型之前需要学习UML不同实体之间关系表达：UML领域模型和类图_Kevin.Chen - 专注前行-CSDN博客_uml领域模型图

2.3 系统用例

上面1.2章节分析了业务用例，现在需要站在系统的角度分析下系统用例，是站在具体的功能实现接角度，也可以简单理解为具体的接口实现，需要考虑不同系统之间的关联关系

2.4 数据模型

根据上面画的领域模型，可以设计具体的数据模型，也就是数据库表结构

2.5 状态机

根据数据库表功能，有些是流水型数据，有些是状态型数据，有些是关联型数据，状态型数据需要对状态机特别关注

下面以一个任务执行的状态机为例进行展示

2.6 数据流转

有些场景下涉及重要的数据，需要重点分析下数据的流转流程方便后续做数据分析

三、系统流程分析

下面详细分析下每个系统流程具体的交互、注意事项、风险点等等

3.1 外卖订购时序

3.1.1 时序图

3.1.2 幂等设计

重点要考虑幂等设计，是保护自己也是保护上游系统。

3.1.3 并发设计

当并发情况下，如何保证功能正确性。

3.1.4 兼容性设计

一般分为两点

1、是如何兼容当前老逻辑

2、发布过程中如何兼容

3.1.5 风险点设计

这个就覆盖点比较多，可能会从系统容量、一致性、安全性等各个方面考虑，在一些极端的业务场景下，如何保证稳定性和正确性。

风险点一般有：权限风险、一致性风险、资损风险、时效性风险、稳定性风险等等，这块等后面单独起章节进行分析。

3.2 xx流程

下面就需要看具体场景的case，这里就不在展开了。

四、非功能性设计

这块也是非常重要的，一般会从以下几个方面进行分析

4.1 可测性设计

比如这个功能不好模拟的时候，如何在线上进行验证，一般会做一些功能辅助验证；

4.2 性能分析

当新的业务接入的时候，需要评估自身的系统支撑的容量和数据存储，可以进行压测来对系统最大容量进行评估，根据压测结果来配置接口的限流。

4.3 并发能力设计

当共享的资源进行抢占，如何保证一致性，是最终一致性？还是强一致性？技术实现方案是什么?当然这块在前面的业务流程分析的时候就应该考虑到了。

4.4 容错能力

如果出现极端的场景，比如系统宕机如何恢复，当断网数据如何处理，等一些场景下的应急措施

4.5 运维能力

如果真的出现一些场景，如何进行数据恢复等等

五、数据分析

这块主要是做一些数据分析，来对业务功能进行评估，比如BI同学想要分析下功能的用户使用情况，想分析下曝光、点击、交易数据，能否很快的拿到数据呢，这快工程同学可能很多情况会忽略，但是这块是非常重要的，在开发阶段，就需要考虑数据埋点等等；

六、接口设计

这块就是系统具体提供的接口能力，接口设计基本上就是在写伪代码了。

6.1 查询接口

接口名称：

com.nii.user.UserAccountFacade#queryInfo

接口入参 UserInfoQueryRequest

字段名称	类型	字段描述	是否必传	备注信息
name	Sting	用户名称	是
userId	D	用户id	是

接口出参UserInfoQueryResponse

字段名称	类型	字段描述	备注信息
name	Sting	用户名称	是
userId	D	用户id	是

七、里程碑

最后就是工作量评估和上线时间点评估


工作项	工作量	负责人
登录模块开发	10D	张三

时间点

上面这些是我简单总结一份技术文档需要包含的内容，可能不是很全，欢迎大家补充。

系统设计（二）如何写技术设计文档相关推荐

先写API文档还是先写代码？你需要这款神器Apifox！
代码未动,文档先行其实大家都知道 API 文档先行的重要性,但是在实践过程中往往会遇到很多困难. 程序员最讨厌的两件事:1. 写文档,2. 别人不写文档.大多数开发人员不愿意写 API 文档的原因是 ...
还在发愁写API文档？推荐一款阿里腾讯都在用的API管理神器！
欢迎关注方志朋的博客,回复"666"获面试宝典前言 ❝ 程序员最讨厌的两件事:1. 写文档,2. 别人不写文档.大多数开发人员不愿意写 API 文档的原因:写文档短期收益远低于付 ...
扫描二维码读取文档_使用深度学习读取和分类扫描的文档
扫描二维码读取文档 To many people's dismay, there is still a giant wealth of paper documents floating out the ...
java开发文档怎么写_程序员该不该写技术文档，怎么写文档，易懂又能提升自己...
最近公司项目的调用量突然涨了一大波,很多系统都纷纷扛不住了,于是需要对系统进行优化,系统优化的第一步,便是梳理业务! 在这个过程中,经常出现了这样一些情况,发现数据库的某些字段,没有注释,也没有一定的 ...
优秀程序猿写技术文档的正确姿势
一.背景写文档是程序猿进阶的一个必要步骤之一. 文档写的清楚,思路就更加清晰,也会让同事高看你一眼,多梳理业务也有很大帮助. 产品经理对需求文档基本是驾轻就熟信手拈来,但是大多数程序猿写技术文档却显 ...
写技术文档需要注意什么
技术文档总是令人头大, 一是文档内容可能不够全面,可读性差,可操作性差二是不知该从何写起,在此简单总结一下之前的内容和思路: 目录一.操作类.代码demo文档二.技术介绍类文档一.操作类.代码 ...
pythoncad二次开发视频_revit二次开发|bim软件二次开发|revit二次开发教程|Revit二次开发技术文档...
二次开发 revit二次开发|bim软件二次开发|revit二次开发教程|Revit二次开发技术文档2019-07-08赞( 0 ) 记录一下CAD二次开发的一些简单实例. 1.helloworld ...
全能程序员系列(十)--开发人员写不好文档？--Word篇
最近帮小伙伴们检查项目技术文档,各种技术报告.需求规格说明书.详细设计文档等,文档格式和内容真是丰富多彩.花样百出,一份份检查真是累到吐血.难道开发人员除了会写代码,其他技能就不需要掌握了吗?下面就是 ...
springboot整合knife4j，从此告别手写接口文档
关于knife4j Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目一开始项目初衷是为了写一个增 ...
Haroopad写接口文档简介
一.所需工具:Haroopad - The next document processor 根据自己的电脑下载安装包,我的是Haroopad-v0.13.1-win-x64.msi,安装,一路next ...

系统设计（二）如何写技术设计文档

为什么要写技术文档?

技术设计文档

一、业务分析

1.1 业务背景

1.2 业务用例

1.3 业务流程

二、系统分析

2.1 系统架构

2.2 领域模型

2.3 系统用例

2.4 数据模型

2.5 状态机

2.6 数据流转

三、系统流程分析

3.1 外卖订购时序

3.1.1 时序图

3.1.2 幂等设计

3.1.3 并发设计

3.1.4 兼容性设计

3.1.5 风险点设计

3.2 xx流程

四、非功能性设计

4.1 可测性设计

4.2 性能分析

4.3 并发能力设计

4.4 容错能力

4.5 运维能力

五、数据分析

六、接口设计

6.1 查询接口

七、里程碑

系统设计（二）如何写技术设计文档相关推荐

最新文章

热门文章

系统设计（二）如何写技术设计文档

为什么要写技术文档?

技术设计文档

一、业务分析

1.1 业务背景

1.2 业务用例

1.3 业务流程

二、系统分析

2.1 系统架构

2.2 领域模型

2.3 系统用例

2.4 数据模型

2.5 状态机

2.6 数据流转

三、 系统流程分析

3.1 外卖订购时序

3.1.1 时序图

3.1.2 幂等设计

3.1.3 并发设计

3.1.4 兼容性设计

3.1.5 风险点设计

3.2 xx流程

四、非功能性设计

4.1 可测性设计

4.2 性能分析

4.3 并发能力设计

4.4 容错能力

4.5 运维能力

五、数据分析

六、接口设计

6.1 查询接口

七、里程碑

系统设计（二）如何写技术设计文档相关推荐

最新文章

热门文章

三、系统流程分析