chapter18-2软件架构编档

1、1 1Documenting Software Architectures(2) 软件架构编档目录1.建立文档包2.记录行为(Documenting Behavior)3.架构文档和质量属性4.记录变化很快的架构(Documenting Architectures That Change Faster Than You Can Document Them)5.敏捷开发中编档软件架构1.建立文档包1.1 记录视图1.2 记录视图以外的信息(Documenting information beyond views)1.3 在线记录，超文本，和维基1.4 遵循发布策略1.5 记录模式1.1 记录视图

2、如图所示是一个记录视图的模板，它一共包括5个部分。1.1 记录视图Section 1 Section 1 基本介绍基本介绍(The primary presentation)(The primary presentation)：对视图中最重要信息的一个简要总结。(1)展现的内容：基本介绍包括了视图中元素以及元素之间的关系。 (2)内容怎样展现：大多数基本介绍是通过图表方式呈现，有时也会以文本的方式呈现，文本呈现的方式比如说有表格或者列表。1.1 记录视图Section 2 Section 2 元元素列表素列表(The element catalog)(The element catalog)：

3、详细介绍在基本介绍中描述的元素、在基本介绍中略去的元素及关系，主要包括4部分。(1)元素和它们的属性：为视图中每个元素命名并罗列出该元素相应的属性。同时也需介绍该元素对这个视图或者架构是否是通用的，元素赋值。 (2)关系和它们的属性：一般情况下，元素的关系记录在基本介绍中，这里记录的是基本介绍中没有介绍到或者介绍过关系的特殊情况(exception)。(3)元素接口(4)元素行为1.1 记录视图Section 3 Section 3 环环境图境图(context diagram)(context diagram)：视图或者视图的一部分怎样与环境联系的。(1)环境：与系统交互交互的部分，环境的实

4、体可以是人、计算机系统、物理对象，比如：传感器或者控制设备。 (2)目的：描述视图的范围。1.1 记录视图Section 4 Section 4 变变化指南化指南(variability (variability guideguide) )：介绍怎样应对(exercise)视图中架构一部分的变动。Section 5 Section 5 理理论基础论基础(rationale)(rationale)：解释为什么在视图中反应的是这种设计。通过选择模式解决的问题及基本原理来证明视图中模式的选择的合理性。1.2 记录视图以外的信息视图以外的信息可以被分成两个部分：1.架构文档的概述：主要讲述文档是怎样被

5、组织存放的以便架构文档的相关使用者(stakeholder)能够找到他有效可信的信息。2.关于架构的信息：关于架构的信息是系统的一个简短概述，主要包括：系统的目的、视图间联系的方式、系统范围设计方法的概述和基本原理、元素列表及它们出现的位置、整个架构的词汇表和英文缩写。1.2 记录视图以外的信息文档控制信息文档控制信息(Document control information)(Document control information)：它主要列出了以下信息：文献出版单位、当前版本号、签发日期和状态(date of issue and status)、历史变更(change history)以

6、及提交文档变更请求的过程。通常在问题前捕获。改变控制工具(change control tools)可以提供大量这类信息。1.2 记录视图以外的信息Section 1 Section 1 文档索引文档索引(Documentation roadmap )(Documentation roadmap )：这个部分包含以下内容，在这个文档中有哪些信息以及在哪里找到它们，它主要包括以下4个部分：(1)范围和总结(scope and summary)：解释了文档的主要用途(purpose)，文档包含了哪些及不包含哪些内容。解释和其他文档的关系，如上流设计文档和下流工程文档。 (2)文档怎样组织的：文档的

7、每个小节在这里都给出信息的简短介绍；当然也可以通过内容注释表的形式来完成。内容注释表不仅包括小节标题，页码数量，同时也给出了每个条目的概要。它为试图查找某一类特定信息的读者提供了一站式购物的模式。1.2 记录视图以外的信息Section 1 Section 1 文档索引文档索引(Documentation roadmap )(Documentation roadmap )：在这个文档中有哪些信息以及在哪里找到它们，它主要包括以下4个部分：(3)视图概述：这小节的主要部分描述了在包中架构包含的视图，对每个视图来说，这一小节给出了以下信息:a.视图的名称，它用的哪一种模式。b.视图的元素类型、关系

8、类型、属性类型。c.在构建视图中使用的语言、建模技术以及分析方法。(4)哪一类stakeholder能够使用文档：描述文档有哪些相关使用者，以及相关使用者用每个视图帮他们解决了哪些问题，这通常通过表格形式表示。这些问题包括用户、收购者、开发者和维护这的问题。1.2 记录视图以外的信息Section 2 Section 2 视图的文档化视图的文档化(How a View Is Documented)(How a View Is Documented)：记录视图时所使用的标准结构(organization)，这个标准结构要么是在章节中描述的，或者是你自己用的，它告诉读者怎么在视图中找到信息。Sec

9、tion Section 3 3 系统概述系统概述(System Overview)(System Overview)：关于系统的功能、用户、任何重要的背景信息或者约束的简短文字描述。这一小节给读者关于系统提供了一个一致的意识模型(consistent mental model)。这一小节将是操作概念文档(concept-of-operation)的指针。1.2 记录视图以外的信息Section 4 Section 4 视图之间的映射视图之间的映射(System Overview)(System Overview)(1)映射的原因：a.架构的所有视图描述的是同一个系统，它代表任意两个视图有共同

10、点。b.理解视图之间的联系帮助读者对架构作为一个整体概念工作有一个深入的了解。(2)映射的关系：视图中元素的映射关系一般来说是多对多的。 (3)映射的表示：视图和视图的关系可以很方便的通过表格的形式表示。视图的元素中的元素通过某种方便查找的顺序罗列出来，元素之间是怎样的关系应该被注释或者介绍。1.2 记录视图以外的信息Section Section 6 6 目录目录(directory)(directory)：帮助读者快速找到更多信息的参考资料集合，主要包括：术语索引、词汇表、缩写列表。Section 5 Section 5 理论基础理论基础(rationale)(rationale)：记录应

11、用到多个视图上的架构决策，主要包括：导致产生这一架构模式的背景、结构约束(organizational constraints)、主要需求以及最终的架构决策，即使用的哪一个架构模式。1.3 在线记录，超文本，和维基(1)链接网页形式的文档：a.包含的内容：具有深层次结构的网页，每个网页通常提供网页概述信息，更深层的信息通过链接的方式呈现。b.优缺点：对于只需要概述信息的人查找信息很容易；对需要详细信息的人来说，查找就相对困难了(搜索引擎)。(2)分享式文档：a.方式：使用已有的可用工具(支持许可策略)。b.例子：wiki(维基)。c.考虑：应该考虑给相关的使用者什么样的使用许可；虽然所有的相关

12、使用者都可以评论、修改架构的信息，但是希望架构能够提供一个“最后批准”机制。1.4 遵循发布策略(1)项目开发计划需要指明项目文档的保存过程，这一文档包括架构文档和变化趋势(current)。(2)架构师应该计划发布文档，以支持主要项目里程碑，这通常意味着让开发人员能够将体系结构用于工作是在在里程碑之前足够长的时间里。例如，每次迭代或增量发布的结束都应该给开发团队提供修改文档。 1.5 记录模式(1) (1) 模式的重要性：模式的重要性：架构师通常使用模式作为设计的起点(13章)。这些模式也提供一个通用的（即不完全）的解决方案，这一解决方案是架构师必须细化和实例化的。(2)(2)记录的内容：记

13、录的内容：首先，记录正在使用的模式。然后说为什么选择这种解决方案的方法，即为什么它对手头要处理的问题很恰当。如果所选择的方法来自一个模式，应该展示手头的问题符合模式的要解决的问题和符合模式的上下文环境。1.5 记录模式(3)(3)说明：说明：使用模式意味着进行连续的设计决策，然后产生架构。这些设计决策表现为新实例化的元素和它们之间的关系。架构师可以在每个阶段记录架构的一个快照。有多少阶段取决于很多事情，其中最重要的是读者有能力跟上(follow)设计过程，以防他们将来必须重新审视它。2.记录行为2.1 面向追踪的语言(trace-oriented language)2.2 综合的语言2.1 面

14、向追踪的语言踪踪迹迹(trace)(trace)是什么是什么：系统在特定状态下对于特定刺激的一系列活动或者交互，描述的是一个顺序。记记录踪迹的录踪迹的4 4种种符号符号：用例、序列图、通信图、活动图。说明说明：a.面向追踪的文档不是综合行为模型的等价物，即它不会追踪所有可能行为。b.还有其他记录踪迹的符号存在，不仅限于4种。2.1 面向追踪的语言用用例例(use cases):用途：用途：描述用户(actors)怎样使用系统满足他们的需求(accomplish their goals)，通常被用于系统捕获功能需求。表表示方法：示方法：UML提供为用例提供图表符号，但并未规定用例的文本应该怎样书

15、写，不可否认，UML用例图能有效地描述用户的概述(overview of actors)和系统的行为；用户的文本描述包括：用例名称及简要的描述、启动用例的角色(主要角色)、参与用例的角色(第二参与者)、事件流、备选流(alternative flows)、不成功实例(nonsuccess cases)。2.1 面向追踪的语言序列图序列图(sequence diagram):用途：用途：描述结构文档中的元素实例的交互顺序，这一实例指被记录的参与这一场景的实例。表示方法：表示方法：二维图，垂直方向表示时间，水平方向表示实例。2.1 面向追踪的语言序列图序列图(sequence diagram):图

16、18.5是一个用UML图画的序列图的例子，每一个对象都有一个生命期，用竖着的虚线表示；序列一般来说是从左到右进行的；对象和对象之间的交互是通过传递消息(这个消息可以是可以是一个函数或者方法，也可能是事件)进行的，用水平的箭头表示；图中的箭头有三种，实线的实三角箭头表示同步信息，实线的空三角表示异步消息，虚线箭头表示返回信息；2.1 面向追踪的语言2.1 面向追踪的语言通信图通信图(communication diagram):用途：用途：展示交互元素，并以数字批注表示每一次交互顺序。说明：说明：a.有效：验证架构能够完成功能需求； b.无效：性能分析时，比如理解某并发行为的重要 性时。2.1

17、面向追踪的语言通信图通信图(communication diagram):序列图和通信图的区别：序列图和通信图的区别：序列图和通信图都属于交互图。这两种图之间的区别在于：序列图基于时间，按时间顺序显示出现的任务；而通信图显示任务和信息(对象)的交互方式，用数字批注表示每一次交互顺序。虽然存在这些根本区别，但这两类图有相同之处相同之处：都用于显示对象和用户如何交互以执行任务。2.1 面向追踪的语言通信图通信图(communication diagram):2.1 面向追踪的语言活动图(activity diagram):用途：用途：展示业务流程的一系列步骤、包含表达条件分支和并发性的符号，同时也

18、包括传递和接收的事件。说明：说明：不展示在特定对象上执行的实际操作。 有效：描述特定工作流的步骤。条件分支允许单个的活动图来表示多路径。表示：表示：箭头表示控制流。可选的，活动图可以指定结构单元或对象执行操作。活动图也可以表达并发。叉节点（描述为与流箭头正交的粗条）将流分割为两个或多个并发的动作流，随后的并发流可以通过连接节点（也称为正交栏）同步到单个流中。连接节点在进程开始之前等待所有传入流。2.1 面向追踪的语言活动图(activity diagram):表示：表示：箭头表示控制流。(可选的，活动图可以指定结构单元或对象执行操作)。活动图也可以表达并发。叉节点（描述为与流箭头正交的粗条）将

19、流分割为两个或多个并发的动作流，随后的并发流可以通过连接节点（也称为正交栏）同步到单个流中。连接节点在进程开始之前等待所有传入流。2.1 面向追踪的语言活动图(activity diagram):开始节点：表达为黑色实心圆点；结束节点：表达为黑色空心圆点；2.2 综合的语言用途用途：与追踪语言不同，表示结构元素的完成行为。这种类型文档包含从初始状态到结束状态的所有可能推断路径。记记录录综合综合性语言的符号性语言的符号：状态机图表符号、架构分析设计语言(AADL)及规范描述语言(SDL)。2.2 综合的语言状态状态机形式机形式：它表示架构元素的行为，因为每一状态是导致这一状态的所有可能历史的抽象

20、。状态状态机语言机语言：状态机图表语言、机器分析与设计语言(AADL)、规范描述语言(SDL)。状态状态机图表符号机图表符号：a.基于状态图的图形形式，由David Harel为建立反应系统而提出的。允许你通过特定输入追踪系统行为；b.UML状态图用方框表示状态，用箭头表示状态间的转换。2.2 综合的语言圆角矩形表示的状态状态 （初态和终态例外）；在状态之间的、包含一些文字描述的有向箭头线，这些箭头线称为转换；转换；转换可以指定一个监护条件，该条件包含在括号中(可选的，不是必须的，本例中没有)，当转换发生的时候，监护条件进行相应的判断，当且仅当判断为真时，进行相应的事件转换；转换也有相应的结果

21、，称为动作，用斜线表示，它发生时仅指转换发生时才执行动作；状态也可以指进入和退出动作。2.2 综合的语言与状态off相关的转换有两个，其触发事件都是turnOn，只不过其监护条件不同。如果对象收到事件turnOn，那么将判断壶中是否有水；如果没水，则仍然处于off状态；如果有水则转为on状态，并执行“烧水”动作；与状态on相关的转换也有两个，如果“水开了”就执行turnOff，关掉开关；如果烧坏了，就进入了终态了；2.2 综合的语言3.架构文档和质量属性如果架构大部分是关于架构属性的，架构文档的主要用途是为了分析(确保架构能够达到它的需求质量属性)，那么质量属性应该在架构文档的什么位置出现。因

22、为缺乏成熟的质量视图，质量属性通过以下5种方式表达：1.理论基础理论基础(rationale)(rationale)。任意设计方法（如架构模式）将有它相关的质量属性。同时在方法选择的解释中可能会包括质量属性需求和权衡(tradeoffs incurred)的满意度讨论，因此你可以在这种解释的位置找到关于质量属性的表达。2.2.元素的接口文档中、服务级协议中、元素展现的属性里。元素的接口文档中、服务级协议中、元素展现的属性里。提供服务的单个架构元素通常具有分配给它们的质量属性，服务的用户需要知道这些服务的及时性(how fast)、安全性和可信性。3.架构文档和质量属性3 3.质量属性通常是用来

23、表示传达一种你查询事物的语言(例子)，熟悉这一语言的人通常能够找到满足这一质量属性需求的架构元素。比如：熟悉这一语言的人知道安全涉及的安全级别，认证用户、审计、防火墙等。性能则涉及缓冲容量，截止日期，周期，事件频率，时钟和定时器等。可用性则涉及平均故障间隔时间，故障转移机制，主要和次要的功能，关键和非关键流程和冗余信息等。 3.架构文档和质量属性4 4.架构文档中通常包括用于展示需求怎样被满足的需求映射。例如如果您的需求文档建立了可用性的需求，那么你应该能够在你的架构文档中查找名称或者引用来找到满足该需求的地方。5 5.文档索引文档索引(Documentation roadmap (Docum

24、entation roadmap ) )。每一个质量属性需求都会有一个相关使用者，他们希望知道它将被满足。对于这些相关使用者，架构应该在文档介绍中提供一个特殊的地方，要么提供相关使用者寻找的东西，要么告诉相关使用者在文件中什么地方找。它应该这样写，如果你是一个性能分析师，你应该注意的进程、线程及其属性（在这里定义），他们在底层硬件平台的部署（这里也可以定义），我们把这样的地方称为文档索引。文档索引。4.记录变化很快的架构(Documenting Architectures That Change Faster Than You Can Document Them)原因原因：无论是在运行时体系结

25、构的变化，或是由于高频发布和部署周期发生的变化，这些变化比记录文档的周期更快。这些系统的架构变化比系统传统的生命周期更快。方法方法：a.记录所有系统版本怎样做是正确的。 b.记录架构中允许更改的方法。即面对变化时，架构允许怎么做。5.敏捷开发中编档软件架构敏捷敏捷：是指为了达到自己的目标，强调快速、灵活的开发，一定程度上忽略项目和流程的软件开发方法。观点观点：a.视图，Beyond和敏捷哲学就一个观点强烈达成一致：如果信息不需要，就不要记录它。所有的文档都应该有一个预期的用途和使用人群，并以一种服务两者的方式生产。 b.文档不是一块铁板，意思就是它不是记录所有其他工作进展情况，直至所有工作全部完成的活动。前面给出的视图选择方法规定了编写文档要优先满足那些需要使用该文档的相关使用者的需要。5.敏捷开发中编档软件架构当使用敏捷原则敏捷原则建立视图和编写Beyond-based的架构文档时，牢记以下6 6点点：a.采用模板或标准组织得到你的设计决策。b. 当且仅当视图有对相关使用者的有一个明确的使用范围时，考虑计划记录一个视图。（Plan to document a view if (but only if) it has a strongly identified stakeholder constituency.）