软件架构文档化

为什么需要把软件架构设计文档化？

即使拥有最好的软件架构，如果利益相关者(stakeholder)不了解它、无法充分理解它以进行使用、构建或修改，或者由于误解而错误地使用，那么所有设计的努力都白费了，因此需要文档化来记录架构

要求

架构文档必须：

足够透明、易于访问，让新成员快速理解
足够具体，能作为蓝图
拥有足够的信息作为分析基础

架构文档既要有规定性，也要有描述性：

对某些受众，它规定了应该是什么，约束未做的决策
对于另一些受众，它描述了事实，回顾已有决策

利益相关者对架构文档的使用至关重要

使用

一般有三种使用方式：

教育
作为利益相关者之间的主要沟通媒介
系统分析与构建的基础

视图

视图让我们能够将软件架构划分为若干个可管理的系统（每个部分对应一个视图），每个视图从特定的视角关注架构的某些方面。文档化一个架构，在很大程度上就是文档化一组相关的视图，并补充那些适用于多个视图的全局信息。

如何选择视图

不同视图支持不同目标和用途
不提倡一个特定的视图，总是按需选择
记录的内容取决于预期如何使用这些文档
确保维护视图的好处大于成本

视图

模块视图

组成元素

模块，即软件的实现单元，提供一套连贯的职责

关系

part of关系：模块视图是部分的，定义了子模块（部分）和聚合模块（整体）之间的关系
depends on关系：定义了两个模块之间的依赖关系，具体的模块视图详细说明依赖关系的含义
is a关系：定义了一个更具体的模块（子模块）和更通用的模块（父模块）之间的关系

约束条件

不同的模块视图可能会施加不同的拓扑约束（先后关系），例如模块之间可见性的限制

使用场合

代码构建蓝图
变更影响分析
规划增量式开发
需求可追溯性分析
传达系统功能和代码库结构
工作分配、进度规划等
展示系统需要管理的信息结构

基本上不会有任何完整的软件架构文档缺少模块视图

C&C视图(Components&Connectors)

组成元素

组件：处理单元和数据存储。提供连接器和其他组件交互
连接器：组件之间交互的路径。连接器有一组角色（接口），表明组件如何使用连接器交互

关系

主要关系是“附件”：组件端口和连接器角色关联，形成组件和连接器的拓扑图
还可能存在“接口委托”：组件端口和一个或多个内部子架构中的端口相关联

约束条件

组件只能连接连接器，不能直连其他组件
连接器只能连组件，不能连其他连接器
连接只能发生在兼容的端口和角色之间
接口委托只能发生在兼容的端口之间
连接器不能单独出现，必须连到组件上

使用场合

展示系统工作方式
指导开发人员实现运行时的交互逻辑
帮助分析运行时的质量属性，如性能、可用性、吞吐量等

C&C视图的注释

UML组件的图元与C&C视图中的组件概念匹配良好，但UML的连接器较为简单，对于需要表达复杂交互协议或属性的C&C连接器，可能需要使用UML组件来模拟，或者通过对简单UML连接器进行扩展坞（stereotype）和标签（tag）注释来表达更丰富的语义。

分配视图

组成元素

软件元素和环境元素
软件元素通常具有对环境的某些需求
环境元素则提供某些属性或能力

关系

allocated to关系，表示某个软件元素被部署或分配到某个环境元素上。

约束条件

因视图而异

使用场合

考虑性能、可用性、安全性
分布式开发中的任务分配
软件版本管理

质量视图

质量视图是针对特定的质量属性或特定的利益相关者关注点而定制的视图。它通常不是一个全新的结构视图，而是通过从已有的结构视图（如模块视图、C&C视图、分配视图）中提取与特定质量相关的元素和关系，并将它们重新组织和呈现，辅以该质量属性特有的分析和说明。

示例

安全视图：展示系统中具有安全职责的组件（如认证服务、授权模块）、它们之间的通信方式（如安全通道）、存储安全信息（如用户凭据、密钥）的数据仓库，以及需要重点保护的敏感数据存储。
通信视图：对于地理上分散或异构的系统尤其有用，可以展示组件间的通信通道、网络拓扑、服务质量（QoS）参数、并发区域等，用于分析网络性能、可靠性（如死锁、竞态条件）

如何选择视图

步骤一：构建利益相关者/视图表

行：利益相关者

列：视图

每个单元格中标注对应利益相关者对该视图的信息需求程度

步骤二：合并视图

寻找表格中的边缘视图：那些只需要概览或只服务于极少数利益相关者
将每一个边缘视图和另一个具有更强利益相关者的视图组合
如下视图通常自然地组合在一起
- 多种不同的C&C视图（如进程视图、服务视图）由于都关注运行时交互，可能适合合并
- 部署视图也常与SOA视图或通信进程视图结合，因为服务和进程最终都需要部署到物理节点上

步骤三：优先级排序和阶段划分

确定视图文档化的优先级和交付顺序。

例如，模块分解视图由于能够帮助项目经理早期进行团队组建、任务分配和预算制定，通常适合较早发布。不必追求一次性满足所有利益相关者的所有信息需求到最详尽的程度，提供80%的关键信息往往已经足够支持他们开展工作。同时，也不必等待一个视图完全完成后再开始另一个视图的文档化，采用广度优先、逐步求精的方式通常更为有效。

视图模板

第一部分：主要介绍，显示视图的元素和关系，以及图例
第二部分：元素介绍，详细介绍第一部分中描述的元素、元素属性、关系属性和元素接口和行为
第三部分：上下文图描述系统如何与环境相关
第四部分：可变性指南，告知视图中可能发生的变化
第五部分：基本原理，为什么设计反映在视图中，并且说明其合理性

视图之外的部分

文档路线图 (Documentation Roadmap)：向读者介绍整个文档的组织结构，说明各章节包含哪些信息以及如何查找。其中应包含一个“视图概述”（View Overview）部分，对文档中包含的每个视图进行简要介绍（名称、采用的模式、元素类型、关系类型、属性类型、使用的表示语言或建模技术等），并指导不同类型的利益相关者如何使用本文档来满足其特定的信息需求。
视图如何文档化 (How a View Is Documented)：说明本文档在记录各个视图时所遵循的标准模板和组织方式（例如，前述的五部分视图模板）。
系统概述 (System Overview)：用简短的文字描述系统的主要功能、目标用户、重要的背景信息或整体性约束。这有助于为读者建立一个关于系统及其用途的一致性心智模型。
视图之间的映射 (Mapping Between Views)：由于不同的视图从不同侧面描述同一个系统，它们之间的元素必然存在关联。本部分旨在揭示这些跨视图的映射关系，帮助读者理解架构如何作为一个统一的整体运作。例如，C&C视图中的一个运行时组件可能是由模块视图中的一个或多个模块“实现”的；模块分解视图中的一个模块可能“包含于”分层视图中的某个特定层次。这些映射关系通常可以用表格的形式来清晰地表示。

原理 (Rationale)：记录那些适用于多个视图或对整个系统具有普遍影响的架构决策及其理由。例如，选择某种基础性的架构风格（如微服务、事件驱动）、做出关于技术选型的重要决策（如编程语言、核心框架）等目录 (Directory)：提供一些参考资料以帮助读者快速查找信息，如术语索引（Index of Terms）、词汇表（Glossary）、缩略语列表（Acronym List）等。
目录 (Directory)：提供一些参考资料以帮助读者快速查找信息，如术语索引（Index of Terms）、词汇表（Glossary）、缩略语列表（Acronym List）等。

除此以外，还要有文档控制信息：列出发布机构、当前版本号、发布日期和状态、变更历史以及提交文档变更请求的流程。

文档包 Documentation Package

即视图 + 视图之外的部分

(•‿•)