如何写出一个好的设计文档?

1.概要

大部分的工程师都不重视设计文档的书写，对于一个需求，都是经过一些简单的讨论，写一个简单的方案甚至就是自己简单的想想就开始进行编码的工作。

往往这种开发方式会导致开发人员对细节考虑不周，开发过程中会带来许多的坑，在今后采坑或者补坑的路上耗费大量的人力，轻则影响上线时间，重则上线了出现case，影响业务。

写设计文档和是能够帮助开发人员完成 是什么->做什么->怎么做 的思路梳理过程。比如，你可能对一个技术或者概念很熟悉了，但是你在要说出来或者写出来给别人看的时候，或许就会发现有些技术的细节你没有考虑清楚。

当你在写一个设计文档的时候，会逼迫你自己去把每一个细节都弄清楚，想明白。这样，在实际的开发过程中才会少踩坑，不踩坑。

2.设计文档

对于一个设计文档的书写，应该满足STAR原则，同时一个好的设计文档需要考虑业内的各种实现方案，不能闭门造车。

基于此我认为主要会分为8个部分。分别为:

项目背景，项目目标，需求分析，方案对比，概要设计，详细设计（存储模型设计，接口设计），开发以及上线计划，方案排期。

对于详细设计中，需要存储应该有存储模型的设计，需要交互应该有相应接口的设计。下面详细说下每个部分的书写要点。

2.1项目背景

主要是梳理下目前系统中的主要问题和痛点，主要问题和痛点的范围覆盖面很广，可以主要从 稳定性、业务、 运营的角度去分析。

对于稳定性，具体的问题可以给出相应的数据指标，比如相关调用时间多少，TP90时间，客诉率，下单成功率等等。
对于业务，具体可以从业务发展，业内痛点来进行分析
运营，具体的问题也可以给出相应的数据指标，比如运维成本高大于XXpd等。

2.2目标

即自己做的这个方案上线后需要达到什么成果，具体目标需要结合项目背景来定。

比如对于稳定性而言，需要降低一半的客诉率，将下单成功率提高到4个9等等。
对于运维角度而言，需要将运维成本降低为0等等。
同样，具体的问题需要具体分析，定目标时可以参考目前业内或者公司内部的相关系统的指标

2.3需求分析

理论上来说，需求分析是PM来做的事情，但是通过需求分析，开发人员能够更加清晰的了解和明确相应用户的需求，也可以通过需求分析了解PM有时的需求是否是“伪需求”。

相关功能的优化以及系统的演进目的都是为了给用户提供更好的服务，在进行需求分析时，开发人员应该尽量的使用下自己的系统，以便能够真正的了解自己的系统。需求分析的要求是需要画出一个 用例图，用来描述用户的所有用例。

2.4方案对比

在进行方案设计时，其实也是一个方案调研的阶段，需要调研业内或者一些开源系统的相关功能实现。并与自身业务相结合，评估出一套最适合自己的业务。

方案对比主要是为了选择出一个适合于自己业务的，有时候不要为了技术而技术，简单合适反而是最佳的选择。

方案对比中可罗列出每个方案的开发流程以及需要注意事项，最后给出方案对比表格以及结论即可

2.5概要设计

在选择好了方案后，需要给出方案的概要设计，在概要设计中，用以描述整个方案的全景设计，一般来说需要包含方案全景设计图、流程图以及时序图。

全景设计图：如果设计方案是对于系统维度，那么设计图中需要体现出当前系统在整个链路中的调用关系，以及当前服务中相关的领域设计，相应领域中应该列出具体的相关功能；如果设计方案是系统内部的优化或者改造方案，那么需要画出内部的调用层级关系图，在图中应该需要标识出系统间的模块关系以及当前方案上线后的调用关系。
流程图：流程图用于描述中方案的详细执行过程，如果方案是系统维度的则没有不用画出。
时序图：时序图的维度可以是针对于服务与服务之间，显示出服务之间的调用，具体的接口可以列出相关服务的内部功能。

2.6详细设计

详细设计中包含方案的对比，存储，接口等详细设计。

存储模型设计

存储模型设计中需要给出相关存储模型图和相关表的DDL设计：

相关存储模型图为相关表的一对一，一对多映射关系，以及当前设计表的相关重要字段
DDL中需要给出相关的建表SQL，建表SQL中每个字段都需要强制给出默认值以及字段详细含义，最后需要给出相应的表索引

接口设计

接口设计中需要给出相应接口的定义，请求和响应对象的定义，如果是rpc接口，比如thrift还需要定义出相关的idl。另外还需要定义接口的超时时间等

接口定义时，可采用swagger来自动生成文档
接口只能新增和适配，没有100%的把握，不能轻易的删除来接口

2.7 开发排期及上线方案

分为开发计划和上线过程

开发计划：主要是列下主体的开发流程，具体可以列出一些方案里程碑的完成时间
上线计划主要包括：
如何进行灰度
如何发布，发布后的check人
如何进行验证
回滚策略

2.8项目排期

给出项目的排期表格，表格中除各计划的相关内容外，还应该包括 预计估时，目前进度，是否delay，delay原因等等。

小结

设计文档不仅仅是写出来给别人看的，而且是一次深入思考的过程，写作的过程就是逼迫自己思考的过程，一篇好的设计文档不仅能使得阅读人员对于所要开发的功能一目了然，还避免了今后的采坑过程。

当然，这篇文章也并没有涵盖所有设计文档的写作，比如也可以通过MindManager画思维导图，或者使用其他的工作，只需要表现的清晰即可。

Kotlin 开发者社区

国内第一Kotlin 开发者社区公众号，主要分享、交流 Kotlin 编程语言、Spring Boot、Android、React.js/Node.js、函数式编程、编程思想等相关主题。

Kotlin 开发者社区