《《软件架构设计文档》模板DOC.pdf》由会员分享,可在线阅读,更多相关《《软件架构设计文档》模板DOC.pdf(18页珍藏版)》请在三一文库上搜索。
1、 Software Architecture Document Version Revision History Date Version Description Author Version: Software Architecture Document Date: Page 2 of 18 目录 1.文档简介4 1.1文档目的4 1.2文档范围4 1.3定义、缩写词和缩略语4 1.4参考资料4 2.架构描述方式4 2.1架构视图阅读指南4 2.2图表与模型阅读指南5 3.架构设计目标5 3.1关键功能5 3.2关键质量属性5 3.3业务需求和约束因素6 4.架构设计原则6 4.1架构设计原
2、则6 4.2备选架构设计方案及被否原因6 4.3架构设计对后续工作的限制(详设,部署等)6 5.逻辑架构视图6 5.1职责划分与职责确定7 5.2接口设计与协作机制8 5.3重要设计包10 6.开发架构视图11 6.1Project划分11 6.2Project 1 11 6.2.1Project目录结构指导12 6.2.2程序单元组织12 6.2.3框架与应用之间的关系(可选)12 6.3Project 213 6.4Project n13 7.运行架构视图13 7.1控制流组织13 7.2控制流的创建、销毁、通信14 7.3加锁设计14 8.物理架构视图14 8.1物理拓扑14 8.2软件
3、到硬件的映射15 8.3优化部署16 Version: Software Architecture Document Date: Page 3 of 18 9.数据架构视图16 9.1持久化机制的选择17 9.2持久化存储方案17 9.3数据同步与复制策略17 10.关键质量属性的设计原理17 Version: Software Architecture Document Date: Page 4 of 18 1. 文档简介 帮助读者对本文档建立基本印象,并为阅读后续内容扫清障碍。 1.1 文档目的 文档目的,非项目目的。否则造成同一项目多个文档之间的内容重复,不利于文档维护。本 小节应指明文
4、档针对的读者对象,最好列出各种读者角色,并说明每种读者角色应该重点阅读 的章节。 1.2 文档范围 文档的 Scope ,非项目的Scope 。否则造成同一项目多个文档之间的内容重复,不利于文档 维护。 1.3 定义、缩写词和缩略语 集中列举文档中的定义、缩写词和缩略语。 1.4 参考资料 本项目经审核的计划书、合同、上级批文;本项目的其他已发表文件;本文档引用的文件资 料,如软件开发标准。具体而言,应包括参考资料的题目(必须)、编号、版本号(必须)、 发表日期、发布方,必要时还可以说明如何使用这些资料。 2. 架构描述方式 为了让读者更好地理解架构文档,在本节应当说明文档涉及的架构视图,并指
5、明为了描 述设计决策用到了哪些图表和模型。 2.1 架构视图阅读指南 以多视图的方式来组织架构文档是大势所趋。推荐的是经过优化的5 视图方法,如下图 所示。 Version: Software Architecture Document Date: Page 5 of 18 2.2 图表与模型阅读指南 对后续文档内容中所用到的建模语言(例如UML )、表格(例如目标-场景 -决策表)等进行 说明。 3. 架构设计目标 功能、质量、约束,一个都不能少。 3.1 关键功能 对架构设计至关重要的功能,包括如下4 类:核心功能、必做功能、高风险功能、独特功 能。所谓独特功能,指这个功能覆盖了上述3 类
6、功能没有涉及到的职责。 3.2 关键质量属性 人之所以痛苦,很多时候是因为追求错误的东西。下图是确定关键质量的5 大原则的整体思 路图。 Version: Software Architecture Document Date: Page 6 of 18 3.3 业务需求和约束因素 创造性地提出约束需求的4 大类型,这是一种极为实用的分类方式。特别是业务需求对架构 设计而言是一种约束的观点,解决了很多架构师的现实困惑。下图标明了4 类约束在“需求层 次-需求方面矩阵”中的位置,可以帮助我们理解产生约束需求的根源。 4. 架构设计原则 投标时经常讲“架构设计原则”,但到了架构文档,这些着眼大局的
7、考虑却“丢了”。 推荐的本文档模板,认为应当把它们“找回来”。 4.1 架构设计原则 着重描述重大的权衡取舍考虑。 4.2 备选架构设计方案及被否原因 在概念架构一级,对备选架构设计方案进行描述,并阐述它们未被采用的原因。这有利于团 队了解当前架构设计方案的来龙去脉,提高团队对当前架构设计方案的认可度。 4.3 架构设计对后续工作的限制(详设,部署等) 架构设计不仅应该包含“指导”,也应该包含重要的“限制”。例如,一份只是说明“性能 和可扩展性都重要”的架构文档,实际上忽视了“可扩展性和性能之间存在的矛盾关 系”。此时,最有效的办法就是在架构文档中明确说明“任何提升可扩展性的架构设计和 详细设
8、计,都应通过架构团队的评审才能引入,以确保性能目标不受重大影响”。 5. 逻辑架构视图 关注点:此架构设计视图的关注点是职责划分。 Version: Software Architecture Document Date: Page 7 of 18 注意:逻辑架构视图无疑是最重要的,但同时也应避免“架构 = 模块 + 接口”等以偏概全的 认识。 参考:任何复杂系统的架构设计都不是一蹴而就的,所以架构师需要理性思维过程的指导。 针对逻辑架构设计这个关键环节,一线架构师实践指南一书给出了2 条建议:一是“以质 疑驱动的螺旋思维”,二是相对分离地考虑“结构方面的切分”和“行为方面的定义”。下图 所示
9、即为推荐的逻辑架构设计理性思维过程。 5.1 职责划分与职责确定 内容:将系统切分成更小的单元,并明确这些单元的职责。具体而言,职责单元可以是层、 子系统、模块、关键类等。 意义:一句话,职责划分不合理,功能和质量都会受到影响。也就是说,功能需求和质量需 求无一不和职责划分相关:一方面,每个功能都是由一条职责协作链完成的;另一方面,职责 划分方式也影响着质量,于是需要职责模型针对特定质量属性要求做出相应调整和优化。很多 人认为架构设计就是职责划分的艺术,虽略显片面,但足以表明职责划分的重要性。 参考:基于对业界大量案例的研究,梳理出了“模块划分的3 种必用手段”,如下图所示, 更多内容可参考一
10、线架构师实践指南一书。 Version: Software Architecture Document Date: Page 8 of 18 5.2 接口设计与协作机制 内容:本节描述接口的定义,以及协作的方式和规范。 意义:恰恰是因为有了各模块之间“未来合作的契约”,分头开发各模块才有了基本保证。 参考:推荐利用“包-接口”图,来识别接口。下图为一个“包-接口”图的示例。 Version: Software Architecture Document Date: Page 9 of 18 参考:推荐使用序列图,建议少用、甚至杜绝使用协作图。下图为一个序列图的示例。 Version: Soft
11、ware Architecture Document Date: Page 10 of 18 5.3 重要设计包 内容:对重要子系统的设计进行“灰盒”级描述。 意义:“每个子系统在架构设计中都应保持黑盒子”的观点,过于理想化了。对于业务层、 通用协作机制而言,经常需要在架构设计期间就引入“灰盒”级描述。 参考:类图和灰盒包图,在本节中较多出现。下图为一灰盒包图示例。 Version: Software Architecture Document Date: Page 11 of 18 6. 开发架构视图 关注点:此架构设计视图的关注点是程序单元组织。 注意:此架构设计视图是必须的、不应“剪裁”
12、掉的。但实际情况却是,很多架构师不关注 开发架构视图,导致很多程序开发人员抱怨“架构师就知道高来高去,架构对编程工作没什么 指导性”。 6.1 Project划分 内容:本节说明整个系统将划分成哪几个Project 来开发,其中,Project 指开发环境所感知 到的“工程”。 意义:基本好处是,有利于开发的组织;而对一些大型的集成系统而言,由于同时涉及了 Web 应用、桌面应用、嵌入式应用等软件形态,所以此时Project 划分其实是不得不做的;最 后,我们推荐核心代码应主动地切分到单独的Project 以进行独立的软件配置管理(SCM ), 以降低核心代码外泄的风险。 参考: Projec
13、t 划分必然是属于“架构设计”的工作,严格来讲仅靠“需求分析”划分的业务 域( Business Area)直接映射到Project 经常意味着工作内容的遗漏。其实,业界不少有见地 的专家已经认识到WBS (工作分解结构)做得太早太草率危害很大,就与“Project 划分不到 位”不无关系。 6.2 Project 1 内容:对 Project 划分后的每个Project 进行目录结构、程序单元组织、框架与应用关系的说 明。 Version: Software Architecture Document Date: Page 12 of 18 6.2.1 Project目录结构指导 内容:关于
14、该Project 一级目录、二级目录等基本目录结构的约定。 意义:为团队并行开发提供必要基础,让不同程序小组看到自己应该负责的程序目录。 参考:不要把所有程序目录的约定都定义得太细,否则这份架构文档就要天天更新了。 6.2.2 程序单元组织 内容:源码、程序库、框架、目标码等类型程序单元之间的编译依赖关系。 意义:或许有人认为这没什么技术含量,但架构设计本来就不是只关心技术含量最高问题 的。君不见,很多软件工程师跳槽到新的企业之后,竟然连一个能正常编译源码的开发环境都 建不起来其实,他们“不知道Project 所依赖的 Library 有哪些”是其中重要原因这本 应在架构文档中给出明确描述的。
15、 6.2.3 框架与应用之间的关系(可选) 内容:框架(Framework )。 意义:既然不适用Framework的开发越来越少了,既然程序员犯的很多错误都和对 Framework理解不到位有关,架构师就有责任明确说明Framework和待开发系统之间的关 系。 参考:下图描述了JGraph 框架和待开发应用的关系。 参考:下图描述了Struts 框架和待开发应用的关系。 Version: Software Architecture Document Date: Page 13 of 18 6.3 Project 2 内容:对 Project 划分后的每个Project 进行目录结构、程序单
16、元组织、框架与应用关系的说 明。 6.4 Project n 内容:对 Project 划分后的每个Project 进行目录结构、程序单元组织、框架与应用关系的说 明。 7. 运行架构视图 关注点:此架构设计视图的关注点是控制流组织。 注意:进程和线程是广为人知的控制流实现技术,但在架构设计思维当中,对于系统软件和 嵌入式软件极为重要的中断服务程序也是控制流,这样利于架构师统一利用不同控制流手段设 计并行和并发。 7.1 控制流组织 内容:控制流有哪些,每条控制流各是何种形式(例如进程、线程、中断服务程序),哪些 软件单元是控制流的起点,整条控制流中分别调用了哪些软件单元。 意义:这是对系统运
17、行时结构的刻画,主要反映系统的动态结构。 Version: Software Architecture Document Date: Page 14 of 18 7.2 控制流的创建、销毁、通信 内容:描述进程、线程和中断服务程序的创建和销毁,以及多条控制流之间的通信关系的定 义。 意义:一旦引入了多条控制流,附加工作就产生了此时控制流的创建和销毁、以及控制 流之间的通信关系往往是必须考虑的。 7.3 加锁设计 内容:系统中有多条控制流在同时运行的情况下,一个经典问题是多于一条控制流可能会同 时修改某些数据结构,而造成数据的不一致。为此,架构师需要关注加锁设计,合理引入临界 区或同步机制。 意
18、义:加锁设计事关系统的正确性。值得注意的是,忽略加锁设计造成的问题往往以“不易 重现的 Bug ”的形式出现,困惑的程序员会对测试人员说,“你看你报的Bug 在我机器上根 本就不存在呀”。 参考:对通用组件、通用模块的设计而言,加锁设计应予以专门关注,思维要点是研究未来 通用模块的各种可能使用场景。 8. 物理架构视图 关注点:此架构设计视图的关注点是物理节点(Node )分布,以及软件到硬件的具体映射关 系。 注意:物理节点即可以是PC 机或服务器,也可以是单片机、单板机或专用机,从而物理架构 视图既适用于描述企业信息系统,也适合于描述嵌入式软件系统。 8.1 物理拓扑 内容:一为硬件选型,
19、二为硬件之间的拓扑连接关系。 意义:对于分布式系统的设计,此节极为重要、而且是必须的。 参考:下图是某企业级系统的物理拓扑图。 Version: Software Architecture Document Date: Page 15 of 18 参考:下图是某嵌入式系统的物理拓扑图。 8.2 软件到硬件的映射 内容:明确每个物理节点上有哪些(一到多个)软件的目标单元,并说明具体的“映射方 式”是安装、是部署、还是烧写、抑或是下载。 意义:如果把此节漏了,就无法表明本文档的主题软件系统和上述硬件、硬件拓扑 Version: Software Architecture Document Date
20、: Page 16 of 18 的关系。 参考:下图所示为设备调试系统中,软件到硬件的映射关系。 8.3 优化部署 内容:为达降低成本、提高性能和可靠性等等目标,应特别关注的部署考虑。 意义:物理架构设计的优劣,造成的成本差异和质量差异,可能是天壤之别。所以必须重 视。 参考:下图展示的,是ADMEMS方法重点推荐的“物理架构设计思维要点”,更多内容可参 考一线架构师实践指南一书。 9. 数据架构视图 关注点:此架构设计视图的关注点是持久化。具体而言,场景化可以借助扁平文件、关系数 据库、实时数据库、Flash 等方式中的一种或多种完成。 注意:本视图单独归档时,请在此节注明其文档名称等信息。
21、 Version: Software Architecture Document Date: Page 17 of 18 9.1 持久化机制的选择 内容:如下持久化机制的一种或多种:扁平文件、关系数据库、实时数据库、Flash 。 意义:不要假设在你的系统中,持久化只需一种机制;随着如今的系统变得越来越复杂,我 们经常需要综合利用不同持久化机制。 9.2 持久化存储方案 内容:持久化数据的格式定义。 意义:统一定义表、文件格式、Flash 数据结构等内容。 9.3 数据同步与复制策略 内容:由于数据分布所引起的,包含数据分布、同步、复制等内容的重要设计决策。 意义:在数据分布的情况下,此节为必
22、须。 参考:在实际中,数据分布的策略绝大多数情况下不会超越下图所示的6 种手段,更多内容 可参考一线架构师实践指南一书。 10. 关键质量属性的设计原理 内容:因软件系统的不同,性能、安全性、可伸缩性、互操作性、可扩展性、可测试性、可 重用性、可维护性等质量属性,都可以是本系统的关键质量属性。本文档的前面部分已经涉及 了关键质量属性的设计决策,而本节更集中、更全面地描述这些架构设计决策,并且阐述“为 什么”这么设计。 意义:只描述架构设计决策本身,不利于读者理解“为什么”这么设计。而且,描述设计原 理有利于在整个软件企业层面促进团队的架构设计能力。 参考:关于描述“为什么”这么设计,目标-场景 -决策表是此方面的卓越工具。下图为示例, 更多内容可参考一线架构师实践指南一书。 Version: Software Architecture Document Date: Page 18 of 18