如何写架构说明书(2)

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

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

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

(一)文档概述

对本架构设计说明书本身进行解释,需要说明清楚本文档背景,即为什么有这个文档,文档的内容范围,预期的读者,包括了哪些需要同步参考的文档,有哪些需要说明术语等,可以分二级标题来写,内容形式如:本文档是对XX系统第XX期项目架构设计/升级/变更进行阐述,主要从整体架构、逻辑架构、接口设计。。。等等各方面详细说明了本系统各架构维度的内容,期望读者为项目管理人员、架构管理人员、运维人员等,在编制过程中参考了XX需求书、XX架构设计规范等;评审一般会关注:   

文档目的及内容范围是否是从架构角度来说明的;

参考文档否则提到了《用户需求规格说明书》、业务知识文档等;

说明术语是否对非通用和非IT缩写进行了解释;

整章是否交代清楚了文档整体上的介绍,使读者对全篇有了大致的了解。

(二)整体架构

描写系统在架构设计时总体的思路及方针,比如采取了分层架构、B/S架构、服务化、数据分离等,同时在设计过程中的一些约束条件,如网络访问约束、开发规范约束、开源产品协议类型等,更重要的是,作为整体架构,一定要将本系统作为一个内部不透明的整体,阐述清楚与之有交互的外部系统都有哪些,与具体外部系统的交互实现的需求是什么?如通过消息总线获取客户信息,通过企业内容管理存取非结构化数据,通过CRM获取客户信息等,并以本系统为中心描绘整个交互关系图,也就是整体架构图。评审一般会关注: 

设计方案表述是否清晰并与实际设计内容一致;

相应的约束是否真实具体,有可检查性;

从整体架构图是否能看清这个系统需要和哪些系统交互,交互的目的是什么;

对于系统间的交互是否正确,外部系统是否能满足交互,如通过CRM获取客户信息可以,获取机构信息可行吗。

(三)逻辑架构

逻辑架构关心的是如何将系统分为不同部分以及各部分之间如何交互,其规定了软件系统由哪些逻辑元素组成以及这些逻辑元素之间的关系(层、子系统、模块等的划分决定+交互接口和交互机制[方法调用、RMI、消息]),因此逻辑架构图需要说清楚本系统包含了哪几项功能模块,模块之间如何交互,交互的目的是实现哪些业务需要。同时,对于具体的功能模块,需要详细说明清楚功能模块的业务意义。评审一般会关注: 

逻辑架构图是否列出了功能模块,及其模块间的交互关系;

是否对图中列出的模块进行了详细说明,使得读者完全了解为什么会有此功能模块,它包括了哪些业务需求。

(四)接口设计

架构设计中对接口的设计包括两方面的内容,一方面是指本系统与外部系统之间的外部接口关系,需要全部例举所有与外部系统的接口,详细解释每一个外部接口的名称(如XX数据推送接口)、所交互的系统名称(如ODS)、交互方式(如Webservice)、交互类别(如后台异步)、接口描述(如本系统通过此接口从ODS中获取XX业务数据);另一方面是指本系统内部功能模块之间的内部调用关系,严格意义说来说这部分属于逻辑架构的一部分,同样需要根据各功能模块的调用实际全部例举,依次解释每个内部接口的名称(如报表服务接口)、主调模块(即主动发起内部调用的功能模块如展示模块)、服务模块(即提供服务的模块,如报表模块)、接口描述(如展示模块通过此接口从报表模块获取报表数据从而实现模块间的解耦),一般来说内部接口调用属于代码级,如果对于需要独立部署的模块而使用远程调用方式的,需要做特别说明。接口是系统复杂度的一种体现,是体现高内聚、低耦合设计原则一个很重要的方面,评审一般会关注:

外、内部接口是否全部例举,是否按照上述对接口各维度的要素进行了解释说明;

对于服务方,是否确实能按照接口所描述的提供相应的服务。

(五)数据架构

数据处理是系统的终极目标,系统在处理过程中有可能需要外部数据的协助,同时系统处理完数据后也可能需要提供给其他系统使用,因此对于数据架构最重要的是讲清楚本系统处理的数据在整个业务数据流链条上的位置,上游有哪些系统为本系统供数,下游哪些系统需要使用本系统的数据。另外,针对系统对数据的处理,需要解释系统设计了哪些关键表,数据初始化采用何种方式、数据冗余如何做,备份如何做等,评审一般会关注:

是否从业务数据流向角度描述清楚了本系统数据与上下游系统数据之间的关系;

针对本系统承载的业务处理,设计了哪些关键实体数据表及其对应,是否能全面覆盖;

有无本系统产生的数据体量估算、数据初始化、数据归档方式、备份策略等。

(六)技术架构

从技术的角度描述本系统在实现过程中用到的关键技术能力,核心的技术组件,包括成熟商业套件以及开源的技术产品。如果是商业套件需要说明使用限制,升级支持等,如果是开源技术需要说明开源协议要求等。可以按分层架构的模式,比如展现层用到了JQuery、Flex之类的,逻辑控制层用到了spring、json等,这个一定是从技术上来说的,对于具体用到的组件,一定要说明组件的版本、功能、适用场景呢。当然,可复用性是技术架构的关键,无论是使用之前的组件还是开源产品,都是通过可复用性来减少资源重复投入,因此在技术组件中需要强调对可复用性的重视,评审一般会关注:

是否对关键技术进行了说明,且能明确表述此技术的成熟度与适用性;

对某些技术的使用是否与企业通用的同类技术有冲突,比如企业内其他系统多使用redis,而本系统确使用memcached;

(七)部署架构

讲清楚系统分为了几个物理部分,每部分需要几台服务器,服务器之间是共同提供服务的集群模式还是一台提供服务一台备用的Master-Slave模式,或者是一台负责写多台多台负责读的读写分离模式,从网络层面来看,系统处于整个企业网络环境的哪个位置如外联区或DMZ区或内网区等。对于需要的服务器,需要说明服务器的软硬件配置信息,如硬件方面几核多大内存、硬盘大小、网络端口数及网络带宽要求,软件方面对操作系统的要求,版本要求,系统及软件参数的调优设置等;是否需要预安装第三方软件,所需软件的版本、部署说明等。评审一般会关注:

是否能从部署架构图看明白系统分几部分进行物理部署;

各部署部分之间的服务器的协作关系;

对硬件服务器的型号、配置、数量等是否明确;

整体部署的网络区域是否明确;

是否需要对相关参数的调优及特殊部署要求进行了说明。

(八)非功能性说明

系统的非功能性包括性能、高可用、可扩展性、可维护、安全性、可移植性,一般来说,对于性能或安全性有较高要求的系统,可以将其独立成一个一级章节来写,比如实时分析类系统要求性能,交易类要求安全,可以将性能和安全作为独立的章节来描述,其他非功能性也可以类似处理。在编写过程中,可以有主次的分别进行阐述,但一定要从系统的实现性来说,即需要描述清楚系统做了何种设计或优化以满足性能,设计了何种校验机制来保障安全,如何通过集群或热备部署来保证可用性,如何讲过去状态化实现可扩展等,这些设计是如何落实在系统里的。即要从系统如何做来满足非功能性的角度,而不是解释具体的非功能性要求是什么。评审一般会关注:

对非功能性的描述是从系统如何实现而不是对系统的要求角度来说的;

每类非功能性都能从需求里面找到对应的需求点,且与业务实际相匹配;

系统对非功能性的实现与系统本身的架构不矛盾,架构可以通过合理的调整来满足;

非功能性的评审需要根据不同系统的业务特点来评审,总体的编制原则是说实现不说需求,毕竟架构设计是要指导后续系统建设实施的。

(九)其他说明

此章节主要对一些辅助的约束或环境进行说明,如约束条件、风险考虑、进度要求、政策限制、环境影响等,根据实际可预见的情况编写即可。如高层对系统总体的要求、开发资源的限制、业务环境的影响、人员知识结构等。评审过程一般不关注具体事项,除非系统有特别要求。

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

 

转载于:https://www.cnblogs.com/zourui4271/p/4870058.html

你可能感兴趣的:(如何写架构说明书(2))