一线大厂——详细设计文档模版

列名code	列名	字段类型	长度	示例
入参
userId	用户ID	String	16	1001
出参
列名code	列名字段	类型	长度	示例
code	返回码	String	8	0：成功，1失败，2跳转充值
message	返回信息	String	64	“网络异常，请稍后再试”
data		User
userId	用户ID	String	16	1001
name	用户名	Sting	32	张三
mobile	手机号	String	16	18888888888

数据库设计

ER关系图（可选），需要设计多张表时可以方便大家理解实体之间的关系

表结构设计（可选）：

表名：user_info

列名	数据类型	注释	默认值	扩展
id	bigint(20) unsigned	主键		AUTO_INCREMENT PRIMARY KEY
create_time	datetime	创建时间（行记录创建时间）
update_time	datetime	更新时间（行记录更新时间）		DEFAULT CURRENT_TIMESTAMP
name	varchar(16)	用户名
mobile	varchar(16)	手机号
is_deleted	tinyint(1)	是否删除（逻辑删除:0正常 -1删除）	0
索引名	类型	包含字段
PRIMARY	Primary	id

建表语句：

CREATE TABLE `db_job_history_session_gather_record` (

  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT COMMENT '主键',

  `create_time` datetime NOT NULL COMMENT '创建时间',

  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '更新时间',

  `name` varchar(16) NOT NULL COMMENT '用户名',

  `mobile` varchar(16) NOT NULL COMMENT '手机号',

  `is_deleted` tinyint(1) NOT NULL DEFAULT 0 COMMENT '是否删除（0正常 -1删除）',

  PRIMARY KEY (`id`)

) ENGINE=InnoDB AUTO_INCREMENT=0 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户信息表'

;

中间件设计

消息队列

描述消息发送者、接收者关系，描述消息发送触发条件，，记录topic、listener相关配置。

示例：topic=“tc_****”，group=“****_group”，listener=“UserPaySuccListener.class”

缓存设计

描述redis、memcache、guavaCache等缓存使用设计方案，包括key、value格式，value值大小，存储数据量级等。

性能设计

性能设计，需要考虑可能的容量规划，包括接口和存储层面，以及之后的性能提升方案，例如增加实例，添加缓存，分库分表，读写分离(CQRS)等等

性能设计需要有相应数据量化指标参考，如：QPS、RT、TP99、内存使用量预估等

安全性设计

安全合规方面的考虑，例如敏感信息加密传输/存储，对C端用户是否存在安全漏洞，例如越权，脱库等等

日志&监控设计

系统稳定性考虑，针对重点核心链路要有完善的监控告警链路覆盖，非重点的功能点需要有相应日志辅助排查问题。

数据兼容方案

根据技术方案类型，如果是技术新老系统改造类的，则需要考虑数据同步方案，双写还是切流，切流的维度是什么，开关如何控制，以及接口访问路由方案，上线步骤等等数据库变更脚本，刷库脚本等等

原型设计

原则上应该产品经理出原型设计，如果产品经理不熟悉，则开发可以给一些原型设计到产品经理侧，辅助产品经理设计

测试回归功能点汇总

需要测试回归的功能点汇总，方便测试评估工作量，以及开发自测功能点罗列

示例：

功能域	细分功能项	验证人	测试关注点	备注
押金购买	押金免押		多次免押场景
支付宝支付		支付余额不足不成功场景支付

功能域

细分功能项

验证人

测试关注点

备注

押金购买

押金免押

多次免押场景

支付宝支付

支付余额不足不成功场景

支付

上线计划（运维计划）

系统发布上线所需要执行的内容和步骤，包含详细的操作指令、sql、配置内容等等

上线CheckList

罗列上线所需的检查项，包括数据库变更脚本，nacos配置，定时任务配置，自有控台配置，运营后台配置，外部依赖服务配置(例如规则引擎，UC等等)，业务验证等

示例：

分类	检查项	检查人	检查工具/平台
数据库	数据库变更脚本
系统配置	nacos配置

实施路径

改造是否需要分期实施，每一期的具体改动点，排期时间，依赖业务方等

举例：

步骤	操作	执行人	执行时间	核验人
步骤1	新增数据库表	DBA	12.01 21:00	开发A同学
步骤2	配置菜单	产品B同学	12.01 21:30	开发A同学
步骤3	nacos配置	运维C同学		开发A同学
步骤4	系统发布	运维C同学		开发A同学
步骤5	定时任务	开发A同学		开发A同学

回滚方案

上线回滚方案，每个技术方案必须考虑，典型的思路是开关控制，开关粒度需要关注

事项	回滚方案	执行人	备注
系统发布	代码版本回滚	运维A	回滚时要按A→B->C的顺序依次回滚

时间规划

功能	负责人	人日
功能1	开发A	1
功能2	开发B	0.5

总开发*人日，预计12.01联调；联调人日2人日，预计12.10提测；测试人日5人日，预计上线时间12.15

问题列表

在设计技术方案时能想到的所有的问题罗列于此，方便记忆，后续这部分问题需要在方案中解决2

举例：

问题	解决方案/结论
用户***怎么办？	方案一：方案二：

问题

解决方案/结论

用户***怎么办？

方案一：

方案二：

风险列表

在设计和开发过程中，会因为各种原因导致我们的方案不能绝对安全地按照预期落地，比如开发工作delay不能按期发布，老版本无法做到全部兼容等。

举例：

问题	解决方案/结论
开发同学A，因紧急需求插入导致delay	协调开发同学B接手部分工作

补充：

设计方案编写标准&评审标准

方案是可转交的：开发同学A编写的技术方案，在评审并交给开发同学B之后，开发同学B可以基于文档直接进行开发，而不需要继续拆解工作内容或完善技术方案。
方案与代码是直接关联的：其他技术同学可以基于技术方案文档，可直接跳转到具体代码，并进行相应代码阅读或问题处理。
方案是直接指导操作的：开发上线过程中，可直接基于方案中的步骤进行按部就班地执行操作，具体命令及操作指引清晰明确。
方案是风险清晰可控的：项目需求研发过程中，偏离方案的部分需要记录并跟踪相应风险项，包括时间风险和内容变更风险，风险前置并沟通详细的解决方案。

面向人群

研发本人：帮助研发同学梳理清楚开发内容，不遗漏改动点，开发过程中快速做到代码实现。
其他研发同学：在排查问题、梳理业务、新同学学习了解的场景中，其他同学可通过技术文档快速定位代码并了解逻辑概况。
测试：测试同学可以通过研发的详细改动点，编写测试用例，文档清晰，测试用例的梳理才不会遗漏。
运维&架构同学：运维同学可通过详细的改动点，评估对系统性能、变更问题的影响面及影响程度，协助研发完成系统上线及系统安全防护。