架构设计三部曲之如何写架构设计说明书

架构设计是需求分析到软件实现的桥梁，也是决定软件质量的关键。编制架构设计说明书是开发人员向架构师转变必定会经历的过程。在架构师整个的成长过程中，必定会经历编制架构设计说明书、评审架构设计说明书以及根据业务需求分析设计系统架构的三个过程。作为一个架构师，我想尝试一下根据这三个过程对不同能力需要，写一次系列文章，包括《架构设计三部曲之如何写架构设计说明书》、《架构设计三部曲之如何评审架构设计说明书》以及《架构设计三部曲之如何做架构设计》，一来可以帮助自己整理思路，重新审视架构设计，二来也可以与大家分享心得，听取大家的意见，共同进步。本篇属于系列中的第一篇。

那么到底如何编写架构设计说明书？该说明书应该包括哪些方面的内容呢？我们知道，架构设计说明书是阐述系统架构具体内容的，根据我之前的文章《 我的架构观-架构未来的发展 》我们明白架构的本质是呈现三大能力：即系统如何 面向最终用户 提供支撑能力、如何面向外部系统提供交互能力、如何面向企业数据提供处理能力。因此从这个角度看，对架构设计说明书的 章节的设置 及章节内容安排 应该要能说明清楚系统架构到底是如何呈现这三种能力的，让我们逐个分析：

1. 系统如何 面向最终用户 提供支撑能力：这一点是要从系统自身的能力来看，即本系统到底应该具备哪些功能，各功能间如何协作以满足支撑最终用户的使用，其实就是要讲 系统的功能架构或逻辑架构 ，回答系统从功能粒度上划分了几个功能模块或子系统，各模块或子系统之间的 内部接口 关系如何等问题。当然还有一个需要考虑的问题，在纵向维度上，随着架构设计理念的不断发展， 逻辑架构模型从最初的展示-数据两层模型，到展示-逻辑-数据（所谓的MVC）三层模型,甚至到 展示-调用接口-逻辑-数据接口-数据五层模型，不同层次表明系统内部设计的精细程度，因此在逻辑架构设计中也需要针对实际情况加上这种分层设计的内容。尤其是对于Browser/Server架构模式的MIS类系统，这种层次更为常见。另外，用户相对于机器来说对系统提供的能力是有个人喜好要求的，不仅要求系统能提供支撑，而且还要更加稳定的、更方便的、灵活的、快速的等提供，这就需要在架构设计说明书中增加所谓 非功能性的设计 ，即需要描述系统的性能、高可用、可扩展性、可维护、安全性、可移植性等。
2. 系统如何面向外部系统提供交互能力：这一点是要把系统当成一个完整的整体，阐述它如何与外部的系统发生调用关系，外部系统为它提供了哪些开放接口，它又为外部系统提供了哪些 外部接口 和能力，同时，在这种相互的调用关系中它处于整个IT架构的何种位置，这其实就是在说系统的 整体架构 。 另外，如果我们把操作系统和硬件服务器也当成一类特殊的外部系统的话，就需要说明系统如何基于操作系统利用硬件服务器来提供计算、存储、网络等能力，系统如何把自己拆分成不同的部分以便部署在服务器上，这其实说的是 部署架构 。
3. 如何面向企业数据提供处理能力：信息系统的原始驱动力就是人们需要借助计算机的强大计算能力来辅助处理大量数据，从而形成可理解的信息，并最终形成可掌握的知识。因此数据处理是系统的根本目的，至关重要，在架构设计说明书中需要单独描述系统对数据的处理能力，即我们所谓的系统 数据架构 。这还是可以从对外和对内两个角度来看，对外即需要说明本系统处理的数据在整个企业数据流中所处的位置，与相关的上下游数据之间的关系，本系统需要从数据上游的外部系统获取哪些数据？又需要为数据下游的系统提供哪些数据；对内需要说明本系统根据业务需求设计了哪些关键数据表，它们之间是何种主外键关系，是否需要从外部导入数据为系统做数据初始化等。当然还有对数据管理的描述，包括如何做数据冗余设计，备份机制，数据安全管理机制等。

     好，分析完这三种能力，我们几乎就找出了架构设计说明书中应该包括的内容，包括整体架构、逻辑架构、数据架构、部署架构、内外部接口、非功能性设计等，如果纯把架构设计作为理论研究，有这些也就够了。但是现实中我们编制架构设计说明书毕竟是用来指导我们后续系统开发的，是需要真正落地实施的，因此就会涉及使用何种技术实现？有哪些关键技术？用到了何种成熟或开源技术组件？复用了哪些之前的技术成果？等等，同时也包括对技术风险的考虑与预防措施。所有这些就是 技术架构 的内容。

综上，我们就可以得到一份完整的架构设计说明书的结构及应该包含的内容，其大致章节应该是这样的：

1. 文档概述：包含项目背景、项目目标、文档版本信息、目标读者、参考文档、名词解释之类的一般文档都会有的章节；
2. 整体架构：主要从整个IT层描述系统所处的位置，与周边关联系统之间的调用关系；
3. 逻辑架构：系统内部功能模块的划分以及各模块功能介绍、相互之间的关系表述；
4. 接口设计：包括系统间的接口设计以及内部功能模块之间的接口设计；
5. 数据架构：本系统与上下游系统间的数据流关系，以及本系统关键数据表设计、数据管理策略等；
6. 技术架构：实施此架构需要用到哪些技术能力，有哪些复用能力及风险；
7. 部署架构：系统如何部署，网络拓扑上有何要求，对硬件服务器有何要求，需要几台，是否需要优化服务器参数；
8. 非功能性设计： 性能、高可用、可扩展性、可维护、安全性、可移植性等。
9. 其他说明：如特别约束条件、风险考虑、进度要求、政策限制、环境影响等；

以上，便是我认为一份较为完整的架构设计说明书应该包括的内容了。

来自为知笔记(Wiz)