Java极客 | 作者 / 铿然一叶
这是Java极客的第 91 篇原创文章
相关阅读：
萌新快速成长之路
JAVA编程思想（一）通过依赖注入增加扩展性
JAVA编程思想（二）如何面向接口编程
JAVA编程思想（三）去掉别扭的if，自注册策略模式优雅满足开闭原则
JAVA编程思想（四）Builder模式经典范式以及和工厂模式如何选？
Java编程思想（五）事件通知模式解耦过程
Java编程思想（六）事件通知模式解耦过程
Java编程思想（七）使用组合和继承的场景
JAVA基础（一）简单、透彻理解内部类和静态内部类
JAVA基础（二）内存优化-使用Java引用做缓存
JAVA基础（三）ClassLoader实现热加载
JAVA基础（四）枚举（enum）和常量定义，工厂类使用对比
JAVA基础（五）函数式接口-复用，解耦之利刃
HikariPool源码（二）设计思想借鉴
【极客源码】JetCache源码（一）开篇
【极客源码】JetCache源码（二）顶层视图
人在职场（一）IT大厂生存法则
0. 前言
本文主要用于对软件设计文档编写比较困惑，不知道该怎么下手的开发者提供参考；仅作为一个提纲，非详细的指导文档。
软件设计涵盖非常多的点，这里仅描述了应用软件系统的一些常见的，重点关注点。
1. 软件设计文档内容决定因素
1.1 软件系统类型
不同软件系统类型会影响影响软件设计文档的内容，例如应用软件系统、嵌入式软件系统、大数据分析软件系统的内容；云化和非云化系统的内容也可能不同。
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 可服务性
例如安装、升级、可维护、调测等。
2.17 可替代性
不依赖特定的技术栈，是否可以很方便的替代，例如将配置中心从nacos替换为阿波罗，将zookeeper替换为etcd，将oracle替换为mysql。
2.18 性能
性能相关的设计，例如并发，并行，需要达到的性能指标，基于性能指标的硬件要求。
2.20 安全
安全相关的设计，涉及面很广，例如数据传输安全，docker容器安全，web安全，java代码安全，开源软件漏洞等等。
2.21 UX设计
界面原型设计，有低保真和高保真，通常是产品经理和UX设计师完成。
2.22 隐私设计
当前不管是内部系统还是外部系统，都会涉及到用户数据，这就涉及到隐私相关的设计，包括隐私申明，数据使用范围，目的，留存时间等等。
2.23 开源软件
开源软件相关的设计，例如开源软件的选型，版本选择，针对不同开源软件license许可的使用设计。
3. 建议
尽管有不少开发者都不愿意写设计文档，感觉耗费时间或者没有必要，但我还是建议编写，最少也是可裁剪，保留核心重要的部分。编写文档至少有以下好处：
- 知识传递 （例如：全局观，前端是否知道整个系统组网，还是只关心页面；如何保证测试人员正确设计测试用例；新来的人如何快速上手）。
- 复杂功能通过设计评审能减少返工，提高开发效率。
- 提升自己的分析和设计能力。
end.
