如何编写软件设计文档

开发运维 2023-08-13 向阳逐梦 手机阅读

Java极客  |  作者  /  铿然一叶
这是Java极客的第 91 篇原创文章

相关阅读：

萌新快速成长之路 JAVA编程思想（一）通过依赖注入增加扩展性 JAVA编程思想（二）如何面向接口编程 JAVA编程思想（三）去掉别扭的if，自注册策略模式优雅满足开闭原则 JAVA编程思想（四）Builder模式经典范式以及和工厂模式如何选？ Java编程思想（五）事件通知模式解耦过程 Java编程思想（六）事件通知模式解耦过程 Java编程思想（七）使用组合和继承的场景 JAVA基础（一）简单、透彻理解内部类和静态内部类 JAVA基础（二）内存优化-使用Java引用做缓存 JAVA基础（三）ClassLoader实现热加载 JAVA基础（四）枚举（enum）和常量定义，工厂类使用对比 JAVA基础（五）函数式接口-复用，解耦之利刃 HikariPool源码（二）设计思想借鉴 【极客源码】JetCache源码（一）开篇 【极客源码】JetCache源码（二）顶层视图 人在职场（一）IT大厂生存法则

  1. 前言

    本文主要用于对软件设计文档编写比较困惑，不知道该怎么下手的开发者提供参考；仅作为一个提纲，非详细的指导文档。

    软件设计涵盖非常多的点，这里仅描述了应用软件系统的一些常见的，重点关注点。

  2. 软件设计文档内容决定因素

    1.1 软件系统类型

    不同软件系统类型会影响影响软件设计文档的内容，例如应用软件系统、嵌入式软件系统、大数据分析软件系统的内容；云化和非云化系统的内容也可能不同。

    1.2 软件设计文档的读者

    不同的读者关注的设计文档内容不同，例如CIO、CTO、架构师、设计师，开发者、测试人员、服务人员，关注点不同，就会通过不同的文档来体现，或者通过一个文档的不同章节来体现。

    1.3 软件设计文档的分类

    软件设计文档的分类不同，其内容也会不同，例如架构设计、系统设计、功能设计、实现设计。

    例如架构设计体现方案、系统关系、系统接口、技术选型；实现设计体现类关系，类职责等等。

    1.4 软件组织

    软件系统越复杂，功能越多，软件组织就越大，就越需要完善的设计文档来保证软件质量，用于设计评审、知识传递、避免理解偏差等等。如果一个软件系统就3、4个人开发（包含验证），且每个人都很有经验，此时往往会省略很多软件设计文档，通过Issue简单描述跟踪则可，当然Issue单中可能会有一些关键点的设计描述。

    1.5 软件成熟度

    组织对软件成熟度要求越高，对软件的交付件要求越高，随之对软件设计文档的要求也越高。

    1.6 小结

    没有一个通用的软件设计模版适用所有系统和场景，需要根据实际情况进行选择和裁剪。

    是否需要软件设计文档，文档包含哪些内容，要根据软件项目、软件系统，组织等因素决定，并非总是需要软件设计文档，不需要为了写设计文档而写，但总的来说，设计文档有助于提升软件质量，及早发现设计问题。

  3. 软件设计文档包含的内容

    不同软件公司都有自己的软件设计文档模版，不一而同，这里仅描述一些常见内容，至于归属哪一类设计文档（架构设计、系统设计、功能设计、实现设计），可自行定义。

    2.1 文档目的

    说明文档的目的，做什么用。

    2.2 范围

    说明文档描述的范围，用于澄清哪些在范围内，哪些不在范围内。

    2.3 约束和声明

    描述系统中的约束以及声明，例如软件依赖（只支持Chrome）、XXX系统依赖等等。

    此章节主要目的也是为了提前声明软件受限提供能力，属于一种保护措施。

    2.4 目标

    软件系统的目标，例如商业目标，架构目标（满足未来XXX年的技术演进），降低成本目标，SaaS化目标，云化目标等等，通过目标牵引，软件设计需要围绕目标达成而设计。

    2.5 上下文

    系统上下文描述，描述系统的边界。

    2.6 核心业务模型

    业务上的核心模型描述，参与人，核心业务实体关系。

    2.7 技术选型

    技术选型，例如： 1）开发语言（Java，Go，Vue，React） 2）中间件选型（ETC/Zookeeper，Nacos/阿波罗） 3）平台选型（阿里云，腾讯云，华为云） 等等。

    2.8 备选方案

    对于复杂业务，同时考虑上市时间，成本等各种因素，并非所有方案都十全十美，有的演进能力有优势，有的成本有优势，提供备选方案用于综合评估使用哪种方案。

    2.9 逻辑架构

    逻辑架构体现系统的组成，系统、子系统、服务、组件、模块，以及它们之间的关系。

    开发视图中服务、组件和代码仓关系。

    构建视图中代码仓和构建的二进制包，部署包的关系。

    2.10 组网

    具体的部署组网，例如安全域、逻辑域划分，部署节点，哪些容器化哪些物理机部署，副本数，容灾等。

    2.11 设计思路

    说明为什么要如此设计的思路，让人对方案更容易理解。

    2.12 特性设计

    特性是从外部视角来看，是对功能的包装，例如微信支持消息在多终端同步，这是一个特性，围绕消息同步，后面会有很多细分功能。

    因此特性通常是对客户而言的，或者对客户来说可以售卖的，例如印象笔记不同账户下体现的这些就是特性：

    image.png

    2.13 功能设计

    具体的功能设计，例如文件上传，日志打印，充值异常充正的处理。

    2.14 可靠性

    保证可靠性的设计，例如冗余设计，容错设计。

    2.15 可用性

    系统可用性设计，例如优雅停机、滚动升级、降级、bypass。

    2.16 可服务性

    例如安装、升级、可维护、调测等。

    2.17 可替代性

    不依赖特定的技术栈，是否可以很方便的替代，例如将配置中心从nacos替换为阿波罗，将zookeeper替换为etcd，将oracle替换为mysql。

    2.18 性能

    性能相关的设计，例如并发，并行，需要达到的性能指标，基于性能指标的硬件要求。

    2.20 安全

    安全相关的设计，涉及面很广，例如数据传输安全，docker容器安全，web安全，java代码安全，开源软件漏洞等等。

    2.21 UX设计

    界面原型设计，有低保真和高保真，通常是产品经理和UX设计师完成。

    2.22 隐私设计

    当前不管是内部系统还是外部系统，都会涉及到用户数据，这就涉及到隐私相关的设计，包括隐私申明，数据使用范围，目的，留存时间等等。

    2.23 开源软件

    开源软件相关的设计，例如开源软件的选型，版本选择，针对不同开源软件license许可的使用设计。

  4. 建议

    尽管有不少开发者都不愿意写设计文档，感觉耗费时间或者没有必要，但我还是建议编写，最少也是可裁剪，保留核心重要的部分。编写文档至少有以下好处：

    • 知识传递 （例如：全局观，前端是否知道整个系统组网，还是只关心页面；如何保证测试人员正确设计测试用例；新来的人如何快速上手）。
    • 复杂功能通过设计评审能减少返工，提高开发效率。
    • 提升自己的分析和设计能力。

end.