Java Geeks | Author / Keng Ran Yiye This is the 91st original article of Java Geeks

0. Preface

This article is mainly used as a reference for developers who are confused about writing software design documents and do not know how to start; it is only an outline, not a detailed guidance document.

Software design covers a lot of points, here only some common and key points of application software system are described.

1. Determinants of software design document content

1.1 Types of software systems

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

1.2 软件设计文档的读者

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

1.3 软件设计文档的分类

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

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

1.4 软件组织

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

1.5 软件成熟度

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

1.6 小结

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

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

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

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

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 特性设计

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

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

2.13 功能设计

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

2.14 可靠性

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

2.15 可用性

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

2.16 可服务性

For example, installation, upgrade, maintainability, and commissioning.

2.17 Substitutability

Whether it can be easily replaced without relying on a specific technology stack, such as replacing the configuration center from nacos to Apollo, replacing zookeeper with etcd, and replacing oracle with mysql.

2.18 Performance

Performance-related design, such as concurrency, parallelism, performance indicators to be achieved, and hardware requirements based on performance indicators.

2.20 Security

Security-related design involves a wide range of areas, such as data transmission security, docker container security, web security, java code security, open source software vulnerabilities, and so on.

2.21 UX Design

Interface prototyping, both low-fidelity and high-fidelity, is usually done by product managers and UX designers.

2.22 Privacy by Design

At present, whether it is an internal system or an external system, user data will be involved, which involves privacy-related design, including privacy statement, data usage scope, purpose, retention time, etc.

2.23 Open source software

Design related to open source software, such as selection of open source software, version selection, and design for the use of different open source software licenses.

3. Suggestions

Although many developers are unwilling to write design documents, and feel that it is time-consuming or unnecessary, I still recommend writing, at least it can be trimmed, and the core important parts are retained. Writing documentation has at least the following benefits:

Knowledge transfer (for example: global view, whether the front end knows the entire system networking, or only cares about the page; how to ensure that testers design test cases correctly; how newcomers get started quickly).
Complex functions can reduce rework and improve development efficiency through design review.
Improve your analysis and design capabilities.

end.

How to Write a Software Design Document