架构设计说明书该怎么写？

小灰灰 2023-03-12 10:56 40阅读 0赞

![format_png][]

![format_png 1][]

![format_png 2][]

前言

架构设计是需求分析到软件实现的桥梁，也是决定软件质量的关键。编制架构设计说明书是开发人员向架构师转变必定会经历的过程。

承接上文：

[如何做架构设计说明书 （点击直达）][Link 1]

本文来说一下如何写架构设计说明书

![format_png 2][]

需求

那么到底如何编写架构设计说明书？该说明书应该包括哪些方面的内容呢？我们知道，架构设计说明书是阐述系统架构具体内容的，  
架构的本质是呈现三大能力：

*  系统如何面向最终用户提供支撑能力
 *  如何面向外部系统提供交互能力
 *  如何面向企业数据提供处理能力

因此从这个角度看，对架构设计说明书的章节的设置及章节内容安排应该要能说明清楚系统架构到底是如何呈现这三种能力的，  
让我们逐个分析：

###     ###

![format_png 2][]

系统如何面向最终用户提供支撑能力：

这一点是要从系统自身的能力来看，即本系统到底应该具备哪些功能，各功能间如何协作以满足支撑最终用户的使用，其实就是要讲系统的功能架构或逻辑架构，  
回答系统从功能粒度上划分了几个功能模块或子系统，各模块或子系统之间的内部接口关系如何等问题。

当然还有一个需要考虑的问题，在纵向维度上，随着架构设计理念的不断发展，  
逻辑架构模型从最初的展示-数据两层模型，到展示-逻辑-数据（所谓的MVC）三层模型,甚至到展示-调用接口-逻辑-数据接口-数据五层模型，

不同层次表明系统内部设计的精细程度，因此在逻辑架构设计中也需要针对实际情况加上这种分层设计的内容。尤其是对于Browser/Server架构模式的MIS类系统，这种层次更为常见。

另外，用户相对于机器来说对系统提供的能力是有个人喜好要求的，不仅要求系统能提供支撑，而且还要更加稳定的、更方便的、灵活的、快速的等提供，  
这就需要在架构设计说明书中增加所谓非功能性的设计，

通过参考技术评审指标，保证系统架构设计满足用户和系统对非功能质量的需求：

####     ####

![format_png 2][]

非功能质量需求的概述

核心非功能质量：

<table> 
 <thead> 
  <tr> 
   <th>核心质量</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>高性能</td> 
   <td>运行效率高，性价比高</td> 
  </tr> 
  <tr> 
   <td>可用性</td> 
   <td>持续可用性，缩短宕机时间，出错恢复，可靠性</td> 
  </tr> 
  <tr> 
   <td>可伸缩</td> 
   <td>垂直伸缩，水平伸缩</td> 
  </tr> 
  <tr> 
   <td>可扩展</td> 
   <td>可插拔，组件重用</td> 
  </tr> 
  <tr> 
   <td>安全性</td> 
   <td>数据安全，加密，熔断，防攻击</td> 
  </tr> 
 </tbody> 
</table>

其他非功能质量：

<table> 
 <thead> 
  <tr> 
   <th>核心质量</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>可监控性</td> 
   <td>快速发现，快速定位，快速解决</td> 
  </tr> 
  <tr> 
   <td>可测试性</td> 
   <td>可灰度，可预览，可Mock，可拆解</td> 
  </tr> 
  <tr> 
   <td>鲁棒性</td> 
   <td>容错性，可恢复性</td> 
  </tr> 
  <tr> 
   <td>可维护性</td> 
   <td>易于维护，监控，运营，扩展</td> 
  </tr> 
  <tr> 
   <td>可重用性</td> 
   <td>可移植性，解耦</td> 
  </tr> 
  <tr> 
   <td>易用性</td> 
   <td>可操作性</td> 
  </tr> 
 </tbody> 
</table>

####     ####

![format_png 2][]

非功能质量需求的具体指标

主要分为4部分：应用服务器、数据库、缓存和消息队列。

*  应用服务器  
    应用服务器是服务的入口，请求流量从这里进入系统，数据库，缓存和消息队列的访问量取决于应用服务器的访问量，  
    对应用服务器的访问量进行评估至关重要，应用服务器主要关心每秒请求的峰值，请求响应时间等指标，  
    通过这些指标可以评估需要的应用服务器资源的数量
 *  ![format_png 3][]

*  数据库  
    根据应用层的访问量和访问峰值，计算出需要的数据库资源的QPS，TPS，每天的数据总量等，  
    由此来评估所需数据库资源的数量和配置，部署结构等。

![format_png 4][]

*  缓存  
    根据应用层的访问量和访问峰值，通过评估热数据占比，计算出的缓存资源的大小，存取缓存资源的峰值，  
    由此来计算所需缓存资源的数量和配置，部署结构等。

![format_png 5][]

*  消息队列  
    根据应用层的访问量和访问峰值，计算需要消息队列传递的数据内容和数据量，  
    计算出的消息队列资源的数量和配置，部署结构等。

<table> 
 <thead> 
  <tr> 
   <th>部署结构</th> 
   <th>容量与性能</th> 
   <th>其他</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>复制模型</td> 
   <td>每天平均数据增量</td> 
   <td>消费线程池模型</td> 
  </tr> 
  <tr> 
   <td>失效转移</td> 
   <td>消息持久的过期时间</td> 
   <td>分片策略</td> 
  </tr> 
  <tr> 
   <td>持久策略</td> 
   <td>每秒读峰值</td> 
   <td>消息的可靠投递</td> 
  </tr> 
  <tr> 
   <td><br></td> 
   <td>每秒写峰值</td> 
   <td><br></td> 
  </tr> 
  <tr> 
   <td><br></td> 
   <td>每条消息的大小</td> 
   <td><br></td> 
  </tr> 
  <tr> 
   <td><br></td> 
   <td>平均延迟</td> 
   <td><br></td> 
  </tr> 
  <tr> 
   <td><br></td> 
   <td>最大延迟</td> 
   <td><br></td> 
  </tr> 
 </tbody> 
</table>

###     ###

![format_png 2][]

系统如何面向外部系统提供交互能力：

这一点是要把系统当成一个完整的整体，阐述它如何与外部的系统发生调用关系，外部系统为它提供了哪些开放接口，它又为外部系统提供了哪些外部接口和能力，

同时，在这种相互的调用关系中它处于整个IT架构的何种位置，这其实就是在说系统的整体架构。另外，如果我们把操作系统和硬件服务器也当成一类特殊的外部系统的话，  
就需要说明系统如何基于操作系统利用硬件服务器来提供计算、存储、网络等能力，系统如何把自己拆分成不同的部分以便部署在服务器上，这其实说的是部署架构。

###     ###

![format_png 2][]

如何面向企业数据提供处理能力：

信息系统的原始驱动力就是人们需要借助计算机的强大计算能力来辅助处理大量数据，从而形成可理解的信息，并最终形成可掌握的知识。

因此数据处理是系统的根本目的，至关重要，在架构设计说明书中需要单独描述系统对数据的处理能力，即我们所谓的系统数据架构。

这还是可以从对外和对内两个角度来看，对外即需要说明本系统处理的数据在整个企业数据流中所处的位置，与相关的上下游数据之间的关系，  
本系统需要从数据上游的外部系统获取哪些数据？又需要为数据下游的系统提供哪些数据；对内需要说明本系统根据业务需求设计了哪些关键数据表，

它们之间是何种主外键关系，是否需要从外部导入数据为系统做数据初始化等。当然还有对数据管理的描述，包括如何做数据冗余设计，备份机制，数据安全管理机制等。

好，分析完这三种能力，我们几乎就找出了架构设计说明书中应该包括的内容，包括:

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

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

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

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

历

[如何做架构设计说明书][Link 1]

史

[我必须得告诉大家的MySQL优化原理][MySQL]

文

[UML (统一建模语言) 各种图总结][UML _]

章

[真实项目案例实战—【状态设计模式】使用场景][Link 2]

![format_png 6][]

欢迎分享转发，有帮助的话点个“在看”

![format_png 7][]

[format_png]: /images/20230312/b92fb732cf614988886b13f3bb919ab5.png
[format_png 1]: /images/20230312/21135eaba587453298707b03676e363a.png
[format_png 2]: /images/20230312/59fc7a13435d4ca58d859dedb1cae6af.png
[Link 1]: http://mp.weixin.qq.com/s?__biz=MzU2NDc4MjE2Ng%3D%3D&chksm=fc44f1a1cb3378b76989f4bfac5a527789c248f2ca66042ec0b074ade65e87327364349b90b6&idx=1&mid=2247484568&scene=21&sn=902102644deeb34dc1d1aaeedf429ac2#wechat_redirect
[format_png 3]: /images/20230312/f6597426f57842f08af3e63fc817a1ab.png
[format_png 4]: /images/20230312/2e52800363454740a8ea570db77673dd.png
[format_png 5]: /images/20230312/638edea6d76c4251b31f19644597dc07.png
[MySQL]: http://mp.weixin.qq.com/s?__biz=MzU2NDc4MjE2Ng%3D%3D&chksm=fc44f1abcb3378bdb661510722d536d039ab075f56f6d0787c4f9cd639f22f0738d789743d99&idx=1&mid=2247484562&scene=21&sn=241929e114d53d3def5e28e0b1b96af4#wechat_redirect
[UML _]: http://mp.weixin.qq.com/s?__biz=MzU2NDc4MjE2Ng%3D%3D&chksm=fc44f173cb3378655798101119d93481d362fec85327b350e649f9109e47f0b9251ad64cb3fa&idx=1&mid=2247484490&scene=21&sn=f7e915b47cd26bee0251e9bd484e7597#wechat_redirect
[Link 2]: http://mp.weixin.qq.com/s?__biz=MzU2NDc4MjE2Ng%3D%3D&chksm=fc44f114cb33780214285c7efd4a5295f3f4c9b882d18a63ec11252d443a7c2fdb575f550f40&idx=1&mid=2247484461&scene=21&sn=eca9b30d7ecd25ba72bf61177b0a0d8c#wechat_redirect
[format_png 6]: /images/20230312/6f7083571bc04ed68b8c37c813c209ca.png
[format_png 7]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9tbWJpei5xcGljLmNuL21tYml6X2dpZi94aWNXWVRTSUN6UnNKRmliZXRqdzJEblVBaG1VQkdrRWF0QXZlMkYxMEtuQjlTVnZzd01lRGxMVzUyY1d3RWljTmoyRU84bG9YQTZMcEhRbTQ5NFdCZUt1US82NDA?x-oss-process=image/format,png