如何评审架构设计说明书

Posted 2021-04-11 侠梦的开发笔记

背景

其实从编制架构设计说明书的角度来看，也可以阐述具体如何编写架构设计说明书

就像高考作文一样，评审总是有些采分点的嘛，那么对于编制架构设计说明书来说

哪些是我们应该准备的采分点呢？我们在编制的过程中需要重点注意哪些章节的哪些内容呢？

这就是我接下来想和大家分享的。

需求

根据第一部文章我们知道一篇架构设计说明书大致章节应该是这样的：

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

关注点

组件选型

• 为什么选 A 不选 B 呢？
• A 不是开源的，出了问题怎么办？
• B 虽然是开源的，但是是 Erlang 写的，公司没人能看懂怎么办？
• C 我看待解决的 Issues 还有很多，有没有去了解过？
• 这个组件在性能方面你是否了解过？
• 开源的免费版本不支持集群怎么办？
• 如果彻底要自己写这个组件有没有可能性？

性能

• 我们需求的 TPS、QPS 和 RT 是多少？
• 整体设计上会做到的 TPS、QPS 和 RT 是多少？
• 随着数据量的增大系统性能会不会出现明显问题？
• 系统哪个环节会是最大的瓶颈？
• 是否打算做压力测试，压力测试方案是怎么样的？
• 怎么提高前端用户的访问流畅性？

可伸缩性

• 每一个环节是否都是可以横向扩展的？
• 扩容需要怎么做手动还是自动？
• 数据库不能横向扩展怎么办？
• 纵向扩展有多少效果？
• 横向扩展是否是线性的？
• 扩展后是否可以提高响应速度？

灵活性

• 是否有了解过产品层面以后会怎么发展？
• 模块 A 是否能拆分出去独立为其它业务服务？
• 模块 B 是否可以替换为另一种第三方数据源？
• 如果流程有变，需要多大的工作量来适应？
• 业务是否可以做到可配？

可扩展性

• 为什么 A 和 B 都有差不多的逻辑？
• 是否考虑到了 A 业务的实现以后还有 B 的可能性？
• 如果现在有两种策略以后扩展到了八种策略怎么做？
• 以后是否可以把这个业务的 H5 前端适配到 PC？

可靠性

• 是否架构中有单点？
• 故障转移是怎么实现的？
• 集群内部故障转移需要多久？
• MQ 或存储出现问题的时候系统会怎么样？
• MQ 或存储出现问题又恢复了系统是否会自己恢复？
• 是否考虑过异地故障转移的方案？
• 是否考虑过多活的方案？
• 是否有数据丢失的可能性？
• 数据丢失后是否可以恢复？
• 系统彻底挂了对其它业务的影响是什么？
• 系统彻底挂了是否可以有线下的方式走业务？

安全性

• 是否彻底避免 SQL 注入和 XSS？
• 是否做了风控策略？
• 是否有防刷保护机制？
• 数据库拖库了会怎么样？
• 是否有数据泄露的可能性？
• 数据的权限怎么控制的？
• 功能的权限是怎么控制的？
• 是否做了日志审计？
• 受到了 DDOS 攻击怎么办？
• 数据传输是否加密验签？

兼容性

• 老的系统打算怎么办？
• 怎么进行新老系统替换？
• 新老系统能否来回切换？
• 别的系统怎么连接你这套新服务？
• 上下游依赖是否梳理过，影响范围多大？
• 上下游改造的难度怎么样？
• 上下游改造有排期吗？
• 上下游改造的计划和通知时间确定了吗？
• 使用了新的数据源数据怎么迁移？
• 使用了新的技术老项目开发能否适应？

弹性处理

• 这个数据重复消费会怎么样？
• 这个接口重复调用会怎么样？
• 是否考虑了服务降级？哪些业务支持降级？
• 是否考虑了服务熔断？熔断后怎么处理？
• 是否考虑了服务限流？限流后客户端表现怎么样？
• 队列爆仓会怎么样？
• 是否考虑了隔离性？

事务性

• 这段业务由谁保证事务性？
• 数据库事务回滚后会怎么样？
• 服务调用了失败怎么办？
• 队列补偿怎么做的？
• 服务调用补偿怎么做的？
• 数据补偿实现最终一致需要多久？
• 在数据不完整的时候用户会感知到吗？

可测试性

• 测试环境和线上的差异多大？
• 是否支持部署多套隔离的测试环境？
• 是否打算做单元测试，覆盖率目标是多少？
• 测试黑盒白盒工作量的比例是怎么样的？
• 是否支持接口层面的自动化测试？
• 是否有可能做 UI 自动化测试？
• 压测怎么造数据？
• 是否可以在线上做压测？
• 线上压测怎么隔离测试数据？
• 是否有测试白名单功能

可运维性

• 每一个组件对服务器哪方面的压力会最大？
• 重新搭建整套系统最快需要多少时间？
• 系统是否可以完全基于源代码构建？
• 系统是否有初始化或预热的环节？
• 系统里哪些环节需要人工参与？
• 数据是否需要定期归档处理？
• 会不会有突发的数据量业务量增大？
• 随着时间的推移如果压力保持不变的话系统需要怎么来巡检和维护？
• 怎么在容器里进行部署？

监控性

• 业务层面哪些指标需要监控和报警？
• 应用层面系统内部是否有暴露了一些指标作监控和报警？
• 系统层面使用的中间件和存储是否有监控报警？
• 是否所有环节都接入了全链路跟踪？
• 出现报警的时候应该由谁来处理？
• 每一个模块是否有固定的主要和次要负责人？
• 有没有可能系统出了问题无法通过监控指标体现？
• 哪些指标需要上大屏由监控进行 7*24 监控？

方案

那么我们依次来看，每个章节在评审过程中需要关注哪些问题，
编写架构设计说明书的人员有针对性的需要提供哪些内容：

• （一）文档概述
  对本架构设计说明书本身进行解释，需要说明清楚本文档背景，即为什么有这个文档，文档的内容范围，预期的读者，包括了哪些需要同步参考的文档，有哪些需要说明术语等，可以分二级标题来写，内容形式如：本文档是对XX系统第XX期项目架构设计/升级/变更进行阐述，主要从整体架构、逻辑架构、接口设计。。。等等各方面详细说明了本系统各架构维度的内容，期望读者为项目管理人员、架构管理人员、运维人员等，在编制过程中参考了XX需求书、XX架构设计规范等；评审一般会关注：
  
  文档目的及内容范围是否是从架构角度来说明的；
  参考文档否则提到了《用户需求规格说明书》、业务知识文档等；
  说明术语是否对非通用和非IT缩写进行了解释；
  整章是否交代清楚了文档整体上的介绍，使读者对全篇有了大致的了解。
• （二）整体架构
  描写系统在架构设计时总体的思路及方针，比如采取了分层架构、B/S架构、服务化、数据分离等，同时在设计过程中的一些约束条件，如网络访问约束、开发规范约束、开源产品协议类型等，更重要的是，作为整体架构，一定要将本系统作为一个内部不透明的整体，阐述清楚与之有交互的外部系统都有哪些，与具体外部系统的交互实现的需求是什么？如通过消息总线获取客户信息，通过企业内容管理存取非结构化数据，通过CRM获取客户信息等，并以本系统为中心描绘整个交互关系图，也就是整体架构图。评审一般会关注：
  设计方案表述是否清晰并与实际设计内容一致；
  相应的约束是否真实具体，有可检查性；
  从整体架构图是否能看清这个系统需要和哪些系统交互，交互的目的是什么；
  对于系统间的交互是否正确，外部系统是否能满足交互，如通过CRM获取客户信息可以，获取机构信息可行吗。
• （三）逻辑架构
  逻辑架构关心的是如何将系统分为不同部分以及各部分之间如何交互，其规定了软件系统由哪些逻辑元素组成以及这些逻辑元素之间的关系（层、子系统、模块等的划分决定+交互接口和交互机制[方法调用、RMI、消息]），因此逻辑架构图需要说清楚本系统包含了哪几项功能模块，模块之间如何交互，交互的目的是实现哪些业务需要。同时，对于具体的功能模块，需要详细说明清楚功能模块的业务意义。评审一般会关注：
  逻辑架构图是否列出了功能模块，及其模块间的交互关系；
  是否对图中列出的模块进行了详细说明，使得读者完全了解为什么会有此功能模块，它包括了哪些业务需求。
• （四）接口设计
  架构设计中对接口的设计包括两方面的内容，一方面是指本系统与外部系统之间的外部接口关系，需要全部例举所有与外部系统的接口，详细解释每一个外部接口的名称（如XX数据推送接口）、所交互的系统名称（如ODS）、交互方式（如Webservice）、交互类别（如后台异步）、接口描述（如本系统通过此接口从ODS中获取XX业务数据）；另一方面是指本系统内部功能模块之间的内部调用关系，严格意义说来说这部分属于逻辑架构的一部分，同样需要根据各功能模块的调用实际全部例举，依次解释每个内部接口的名称（如报表服务接口）、主调模块（即主动发起内部调用的功能模块如展示模块）、服务模块（即提供服务的模块，如报表模块）、接口描述（如展示模块通过此接口从报表模块获取报表数据从而实现模块间的解耦），一般来说内部接口调用属于代码级，如果对于需要独立部署的模块而使用远程调用方式的，需要做特别说明。接口是系统复杂度的一种体现，是体现高内聚、低耦合设计原则一个很重要的方面，评审一般会关注：
  外、内部接口是否全部例举，是否按照上述对接口各维度的要素进行了解释说明；
  对于服务方，是否确实能按照接口所描述的提供相应的服务。
• （五）数据架构
  数据处理是系统的终极目标，系统在处理过程中有可能需要外部数据的协助，同时系统处理完数据后也可能需要提供给其他系统使用，因此对于数据架构最重要的是讲清楚本系统处理的数据在整个业务数据流链条上的位置，上游有哪些系统为本系统供数，下游哪些系统需要使用本系统的数据。另外，针对系统对数据的处理，需要解释系统设计了哪些关键表，数据初始化采用何种方式、数据冗余如何做，备份如何做等，评审一般会关注：
  
  是否从业务数据流向角度描述清楚了本系统数据与上下游系统数据之间的关系；
  针对本系统承载的业务处理，设计了哪些关键实体数据表及其对应，是否能全面覆盖；
  有无本系统产生的数据体量估算、数据初始化、数据归档方式、备份策略等。
• （六）技术架构
  从技术的角度描述本系统在实现过程中用到的关键技术能力，核心的技术组件，包括成熟商业套件以及开源的技术产品。如果是商业套件需要说明使用限制，升级支持等，如果是开源技术需要说明开源协议要求等。可以按分层架构的模式，比如展现层用到了JQuery、Flex之类的，逻辑控制层用到了spring、json等，这个一定是从技术上来说的，对于具体用到的组件，一定要说明组件的版本、功能、适用场景呢。当然，可复用性是技术架构的关键，无论是使用之前的组件还是开源产品，都是通过可复用性来减少资源重复投入，因此在技术组件中需要强调对可复用性的重视，评审一般会关注：
  
  是否对关键技术进行了说明，且能明确表述此技术的成熟度与适用性；
  对某些技术的使用是否与企业通用的同类技术有冲突，比如企业内其他系统多使用redis，而本系统确使用memcached；
• （七）部署架构
  讲清楚系统分为了几个物理部分，每部分需要几台服务器，服务器之间是共同提供服务的集群模式还是一台提供服务一台备用的Master-Slave模式，或者是一台负责写多台多台负责读的读写分离模式，从网络层面来看，系统处于整个企业网络环境的哪个位置如外联区或DMZ区或内网区等。对于需要的服务器，需要说明服务器的软硬件配置信息，如硬件方面几核多大内存、硬盘大小、网络端口数及网络带宽要求，软件方面对操作系统的要求，版本要求，系统及软件参数的调优设置等；是否需要预安装第三方软件，所需软件的版本、部署说明等。评审一般会关注：
  是否能从部署架构图看明白系统分几部分进行物理部署;
  各部署部分之间的服务器的协作关系；
  对硬件服务器的型号、配置、数量等是否明确；
  整体部署的网络区域是否明确；
  是否需要对相关参数的调优及特殊部署要求进行了说明。
• （八）非功能性说明
  系统的非功能性包括性能、高可用、可扩展性、可维护、安全性、可移植性，一般来说，对于性能或安全性有较高要求的系统，可以将其独立成一个一级章节来写，比如实时分析类系统要求性能，交易类要求安全，可以将性能和安全作为独立的章节来描述，其他非功能性也可以类似处理。在编写过程中，可以有主次的分别进行阐述，但一定要从系统的实现性来说，即需要描述清楚系统做了何种设计或优化以满足性能，设计了何种校验机制来保障安全，如何通过集群或热备部署来保证可用性，如何讲过去状态化实现可扩展等，这些设计是如何落实在系统里的。即要从系统如何做来满足非功能性的角度，而不是解释具体的非功能性要求是什么。评审一般会关注：
  对非功能性的描述是从系统如何实现而不是对系统的要求角度来说的；
  每类非功能性都能从需求里面找到对应的需求点，且与业务实际相匹配；
  系统对非功能性的实现与系统本身的架构不矛盾，架构可以通过合理的调整来满足；
  非功能性的评审需要根据不同系统的业务特点来评审，总体的编制原则是说实现不说需求，毕竟架构设计是要指导后续系统建设实施的。
• （九）其他说明
  此章节主要对一些辅助的约束或环境进行说明，如约束条件、风险考虑、进度要求、政策限制、环境影响等，根据实际可预见的情况编写即可。如高层对系统总体的要求、开发资源的限制、业务环境的影响、人员知识结构等。评审过程一般不关注具体事项，除非系统有特别要求。

以上就是整个架构设计说明书的评审内容，也是各章节编制的指导思路，本人根据在实际工作中的一些体会粗略总结，不一定全面，但是对整个编制会有一些帮助，和大家一起讨论学习。

●

●

●

●

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