4.6软件架构的常见文档类型

通常会使用一系列不同的文档来描述前面章节所涵盖的架构信息。本节将对这些文档进行概述。

4.6.1 核心架构描述

核心架构描述是软件架构的核心文档。在可能的情况下，它包含与架构相关的所有信息，例如: • 架构的任务、目标（愿景）、质量要求和利益相关者 • 技术和组织的条件与约束 • 使用的视图、决策和模式 • 技术概念 • 质量评估 • 识别风险 • 等等......。

模板文档是一个有用的工具。例如，[ARC42] 中的文档模板在很大程度上遵循了本章前面部分所描述的内容。

一个核心架构描述可能会变得相当大，因此在单个文档中对其进行描述（和维护）可能用处有限。可以使用各种工具来管理这样的描述的内容。一些典型的选择是 • 文档 使用常见的文字处理软件创建的文档通常易于使用和管理，只要它们不变得太大。 • CASE/MDA/UML工具 具有强大报告生成功能的建模工具在创建文档时可能非常有用（也见第 6 章）。然而，不应低估此类工具针对特定项目的初始配置所需的努力，特别是对于小型项目。这种方法的主要优点是在维护阶段（特别是对于重复生成架构文档）的自动化程度显著提高，因为 UML 图和代码段可以被合并到新的文档版本中，而无需复制和粘贴。 • HTML页面或维基百科 像维基这样“可能更务实”的工具可能在文档和建模工具之间提供一个有用的折衷。 • 任何混合形式 第 6 章讨论了许多用于创建软件架构的其他软件工具。

4.6.2 架构概述

架构概述作为核心架构描述的简短、易读的总结。如果可能，它不应超过 30 页。它涉及类似的内容，但仅限于关键方面，如核心视图、主要质量要求和核心决策。

如果由于时间或精力等原因无法创建详细的核心架构描述，架构概述可以作为完整描述的简化替代方案。

4.6.3 文件概述

文件概述是一个目录，作为所有与架构相关文件的每个项目或每个应用程序的索引，并记录它们的依赖关系。应该定义关于此目录的结构以及可以在哪里找到它的组织策略。还应包括关于哪些文件应由谁阅读（即项目中的哪个角色以及按什么顺序）的信息。

4.6.4 概述演示

概述演示是一组幻灯片，在最多一小时内展示架构（用技术术语）。 适合管理层的变体应在十分钟内总结核心陈述和业务效益。

4.6.5 架构壁纸

“架构壁纸”用于呈现大量架构方面的完整概述。在实践中，这通常是一组海报大小的打印件，详细说明了带有细化、质量方面等的视图表示。这些被挂在墙上或 Metaplan 板上，允许对特定主题进行互动讨论 - 例如，在架构和开发团队之间。

请注意：“架构壁纸”是促进讨论的极其有用的工具，但不是万能的。这样的大规模描绘可能会对负责实现、测试和操作软件系统的人员产生威慑作用。

4.6.6 文档手册

手册解释了整个项目文档的结构和功能。它也是解释所使用符号的合适位置。

4.6.7 技术信息

技术信息由一个或多个文档组成，包含对项目开发人员和测试人员重要的信息。应当用于存储关于开发方法和编程指南，以及关于系统的构建、启动和测试的信息（也见 4.5 节）。

4.6.8 外部接口的文档

应特别关注外部可见接口的文档。这些对于整个系统与其环境的交互具有核心重要性。

不幸的是，在实际项目中，外部接口经常成为耗时的问题区域。在项目的早期阶段就应始终给予它们足够的关注，在这个阶段可以更轻松地调整个别细节。在早期阶段在接口文档上投入更多精力，比创建非常好的图表或在视图描述中添加最后一点语法上的 UML 细化更有价值。

4.6.9 模版

对于接口描述，遵循一致的模式也是有用的。下表列出了接口描述的一些典型元素：

表4-9Typical接口描述元素