关于 arch42

arc42 是用于软件和系统架构文档的模板，由 Peter Hruschka 博士、Gernot
Starke 博士和其他贡献者创建、维护和拥有。该模板的版本号为8.2 EN.（基于
AsciiDoc版本），发布日期为2023年1月。

您可以在 arch42.cn 上找到更多信息。

这个版本的模板包含了一些帮助和解释，用于熟悉 arc42 并理解其中的概念。
但如果要为您自己的系统编写文档，最好使用简洁版。

• 目录
  • 介绍和目标
    • 需求概述
    • 质量目标
    • 利益相关者
  • 架构约束
  • 系统范围和背景
    • 业务背景
    • 技术背景
  • 解决方案策略
  • 构建块视图
    • 白盒整体系统
    • Level 2
    • Level 3
  • 运行时视图
    • 运行时场景1
    • 运行时场景2
    • 运行时场景n
  • 部署视图
    • 基础设施 level 1
    • 基础设施级别2
  • 架构决策
  • 质量要求
    • 质量树
    • 质量场景
  • 风险和技术债务
  • 术语表

目录

介绍和目标

描述了软件架构师和开发团队必须考虑的相关要求和驱动力。这些包括：

• 基础业务目标
• 基本功能
• 基本功能需求
• 架构的质量目标
• 相关利益相关者及其期望

需求概述

• 内容
  功能需求的简要描述、推动因素、需求摘要。链接至希望存在的需求文档（包括版本号和查找信息）。

• 动机
  从最终用户的角度，系统被创建或修改以改善对业务活动的支持和/或提高质量。

• 形式
  简短的文本描述，可能以表格用例格式呈现。如果存在需求文档，本概述应参考这些文档。 请尽量保持这些摘录的简洁性。
  在确保文档可读性的基础上，注意避免与需求文档的潜在冗余。请参阅arc42文档中的介绍和目标。

质量目标

• 内容
  对于架构而言，对利益相关者最重要且具有最高完成重要性的前三个（最多五个）质量目标。我们真的指的是架构的质量目标。
  请不要将其与项目目标混淆。它们不一定是相同的。 请考虑 ISO 25010 标准的潜在主题概述。
  

• 动机
  您应该了解最重要的利益相关者的质量目标，因为它们将影响基本的架构决策。确保对这些质量非常具体，避免使用术语。

• 形式
  按优先级排序的具有质量目标和具体场景的表格

利益相关者

• 内容
  系统利益相关者的明确概述，即所有应该了解架构的人员、角色或组织，包括：

  • 应了解架构的人员
  • 必须对架构表示认同
  • 必须与架构或代码一起工作
  • 需要架构文档开展工作的人员
  • 必须就系统或其开发做出决策

• 动机
  您应当了解系统开发中涉及的所有各方，或者受到系统影响。否则，在开发过程后期可能会遇到令人不快的意外。这些利
  益相关者确定了您工作及其结果的程度和详细级别。

• 形式
  包含角色名称、个人名称以及他们对架构及其文档的期望的表格。

架构约束

• 内容
  会限制软件架构师在设计和实施决策或开发过程决策方面的自由的任何要求。这些约束有时超出个别系统，适用于整个组织和公司。

• 动机
  架构师应准确了解他们在设计决策中的自由度以及必须遵守约束的地方。约束必须始终得到处理；尽管它们可能是可协商的。

• 形式
  简单的约束表格，并附上解释。如果需要，您可以将其细分为技术约束、组织和政治约束以及规范（例如编程或版本控制指南，文
  档或命名约定）。 请参阅arc42文档中的架构约束。

系统范围和背景

• 内容
  系统范围和背景 - 顾名思义 - 从所有通信伙伴（相邻系统和用户，即系统的上下文）中划定了您的系统范围。 因此，
  它指定了外部接口。必要时，区分业务背景（特定领域的输入和输出）和技术背景（通道、协议、硬件）。

• 动机
  领域接口和与通信伙伴的技术接口是您系统最关键的方面之一。 确保您完全理解它们。

• 形式
  多种选择:

  • 上下文图
  • 通信伙伴及其接口列表。请参阅arc42文档中的场景和范围。

业务背景

• 内容
  所有通信合作方（用户、IT系统等）的规范，包括领域特定的输入和输出或接口的解释。可以选择性地添加领域特定的
  格式或通信协议。

• 动机
  所有利益相关者都应了解与系统环境交换的数据。

• 形式
  展示系统作为黑盒的各种图表，以及指定与通信合作方的领域接口。 另外（或另外），您可以使用表格。表格的标题是您系统
  的名称，三列包括通信合作方的名称、输入和输出。
  <Diagram or Table>
  <optionally: Explanation of external domain interfaces>

技术背景

• 内容
  技术接口（通道和传输媒体），连接您的系统与其环境。此外，将领域特定输入/输出映射到通道，即解释哪个输入/输出使用哪个通道。

• 动机
  许多利益相关者基于系统与其上下文之间的技术接口而做出架构决策。特别是基础设施或硬件设计人员会决定这些技术接口。

• 形式
  例如，使用UML部署图描述到相邻系统的通道，以及显示通道与输入/输出之间关系的映射表。

解决方案策略

• 内容
  关于塑造系统架构的基本决策和解决方略的简要总结和解释。其中包括：

  • 技术决策
  • 对系统的顶层分解的决策，例如使用架构模式或设计模式
  • 关于如何实现关键质量目标的决策
  • 相关的组织决策，例如选择开发流程或将某些任务委派给第三方。

• 动机
  这些决策构成了您架构的基石。它们是许多其他详细决策或实施规则的基础。

• 形式
  保持对这些关键决策的解释简洁。
  阐述决策的动机以及为什么要这样决定，根据问题陈述、质量目标和关键约束。参考以下部分中的详细信息。
  请参阅arc42文档中的解决方案策略。

构建块视图

• 内容
  构建块视图显示系统静态分解成构建块（模块、组件、子系统、类、接口、包、库、框架、层、分区、层、功能、宏、操作、数据结构等），
  以及它们的依赖关系（关系、关联等）。这个视图对于每个架构文档来说都是必需的。类比于一个房子的平面图。

• 动机
  通过抽象使源代码结构更易理解，从而保持对系统源代码的概观。
  这使您能够在抽象级别与利益相关者进行沟通，而不泄露实现细节。

• 形式
  构建块视图是一个分层的黑盒和白盒（参见下图）及其描述的集合。

  

  Level 1 是整个系统的白盒描述，以及所有包含的构建块的黑盒描述。
  Level 2 放大到Level 1的一些构建块。 因此，它包含Level 1中选择的若干构建块的白盒描述，以及其内部构建块的黑盒描述。
  Level 3 放大到Level 2的若干构建块，依此类推。

  请参阅arc42文档中的“构建块视图”。

白盒整体系统

这里描述了使用以下白盒模板对整体系统进行分解。它包括：

• 一个概述图
• 对分解的动机
• 包含构建块的黑盒描述。对于这些，我们为您提供以下选择：
  • 使用一个表格，简洁明了地列出所有包含的构建块及其接口
  • 根据黑盒模板列出构建块的黑盒描述（参见下文）。根据您选择使用的
    工具，此列表可以是子章节（在文本文件中）、子页面（在Wiki上）
    或嵌套元素（在建模工具中）。
• （可选：）重要的接口，这些接口在构建块的黑盒模板中没有解释，但
  对于理解白盒极为重要。由于有许多方法可以指定接口，所以我们没有
  为它们提供特定的模板。在最坏的情况下，您需要指定和描述语法、语
  义、协议、错误处理、限制、版本、质量、必要的兼容性以及其他许多
  内容。在最好的情况下，您只需要提供例子或简单的签名。
  <Overview Diagram>

动机
<text explanation>

包含的构建块
<Description of contained building block (black boxes)>

重要接口
<Description of important interfaces>

对于 level 1 的黑盒，你可以使用下面的表格形式来描述这些黑盒，并根据以下模式描述它们的名称和责任：

如果您使用黑匣子描述清单，那么您需要为每个重要的构建块填写一个单独的黑匣子模板。其标题为黑匣子的名称。

• <名字黑盒1>

  在这里，您根据以下黑盒模板描述<黑盒1>：

  • 目的/责任
  • 接口（当它们不是作为单独段落提取时）。这些接口可能包括质量和性能特征。
  • （可选）黑盒的质量/性能特征，例如可用性，运行时行为，……
  • （可选）目录/文件位置
  • （可选）已实现的需求（如果您需要与需求的可追溯性）。
  • （可选）开放问题/问题/风险

  <Purpose/Responsibility>
  <Interface(s)>
  <(Optional) Quality/Performance Characteristics>
  <(Optional) Directory/File Location>
  <(Optional) Fulfilled Requirements>
  <(optional) Open Issues/Problems/Risks>

• <名字黑盒2>
  <black box template>

• <名字黑盒n>
  <black box template>

• <名字接口1>
  …

• <名字接口m>

Level 2

在这里，您可以指定某些 level 1 的构建块的内部结构，作为白盒。您必须决定系统中哪些构
建块非常重要，值得进行如此详细的描述。请优先考虑相关性而不是完整性。指定 重要 、
令人惊讶 、有风险 、 复杂 或 不稳定的 构建块。忽略系统的 正常 、 简单 、无趣 或 标准化 部分。

• 白盒<构建块1>
  …描述构建块1的内部结构。
  <white box template>

• 白盒<构建块2>
  <white box template>
  …

• 白盒<构建块m>
  <white box template>

Level 3

在这里，您可以将某些构建块的内部结构作为白盒进行详细说明。
对于架构的更详细层次，您可以复制arc42的这部分内容以获取额外的级别。

• 白盒<_构建块x.1_>
  指定了构建块 x.1 的内部结构。
  <white box template>

• 白盒<_构建块x.2_>
  <white box template>

• 白盒<构建块y
  <white box template>

运行时视图

• 内容

  运行时视图描述了系统构件在以下领域中的场景形式的具体行为和交互：

  • 重要用例或功能：构件如何执行它们？
  • 关键外部接口的交互：构件如何与用户和相邻系统合作？
  • 操作和管理：启动、启动、停止
  • 错误和异常场景

  备注：选择可能场景（序列、工作流程）的主要标准是它们的架构相关性。描述大量场景并不重要。您应该更多地记录代表性的选择。

• 动机

  您应了解系统构件（实例）的运行时执行任务和通信方式。您主要会在文档中记录场景，以便将架构传达给不太愿意或能够阅读和
  理解静态模型（构件视图、部署视图）的利益相关者。

• 形式
  有许多符号可以描述场景，例如：

  • 以步骤的编号列表（自然语言）
  • 活动图或流程图
  • 时序图
  • BPMN或EPC（事件过程链）
  • 状态机
  • …

  请参阅arc42文档中的运行时视图。

运行时场景1

• <插入运行时图表或对该场景的文字描述>
• <插入此图表中所描绘的构建块实例之间交互的显著方面的描述>

运行时场景2

…

运行时场景n

部署视图

• 内容
  部署视图描述了：

  1. 用于执行系统的技术基础设施，包括地理位置、环境、计算机、处理器、通道和网络拓扑等基础设施元素，
  2. (软件) 构建块与基础设施元素之间的映射。

  通常，系统在不同的环境中执行，例如开发环境、测试环境、生产环境。在这种情况下，您应记录所有相关环境。

  特别是在以下情况下应记录部署视图：当您的软件作为多台计算机、处理器、服务器或容器组成的分布式系统执行时，或者当您设计和构建自己的硬件处理器和芯片时。

  从软件的角度来看，只需捕获基础设施的那些元素，以展示构建块的部署即可。硬件架构师可以超越这一点，根据需要捕获基础设施的任何细节。

• 动机
  没有硬件，软件就无法运行。这些基础设施会影响系统和/或一些横切概念。因此，有必要了解基础设施.

  也许在第3.2节的技术背景中已经包含了最高级别的部署图，将您自己的基础设施作为一个黑盒。

  在本节中，可以使用额外的部署图放大这个黑盒：
  • UML提供了部署图以表达这种视图。当您的基础设施更复杂时，可以使用它，可能带有嵌套图。
  • 当您的(硬件)利益相关者更喜欢使用与部署图不同的图表类型时，可以让他们使用任何能够显示基础设施节点和通道的图表。

  请参阅arc42文件中的部署视图。

基础设施 level 1

• <基础设施元素1>
  描述（通常结合图表和文本）：

• 将系统分布到多个位置、环境、计算机、处理器等，以及它们之间的物理连接
• 对这种部署结构的重要论证或动机
• 这种基础设施的质量和/或性能特征
• 软件构件与这种基础设施的元素的映射

对于多个环境或替代部署，请复制并调整arc42的这一部分，以适应所有相关环境。
<Overview Diagram>

动机
<explanation in text form>

质量和/或性能特征
<explanation in text form>

构建块到基础设施的映射
<description of the mapping>

• <基础设施元素2>
• <基础设施元素n>

基础设施级别2

在这里，您可以包含 level 1 的一些基础设施元素的内部结构。
请针对每个选定的元素从 level 1 复制结构。

<Infrastructure Element 1>
<diagram + explanation>
<Infrastructure Element 2>
<diagram + explanation>
…
<Infrastructure Element n>
<diagram + explanation>

##横切概念

• 内容
  本部分描述了适用于系统多个部分（即切面）的整体主要规定和解决方案想法。这些概念常常涉及多个构建块。它
  们可以涵盖许多不同主题，例如：
  •模型，特别是领域模型
  •架构或设计模式
  •使用特定技术的规则
  •总体性（跨切面）的主要技术决策
  •实现规则

• 动机
  概念形成了架构的概念一致性（一致性，同质性）的基础。因此，它们对于实现系统内在质量是一个重要的贡献。
  其中一些概念无法分配给单个构建块，例如安全性或安全性。

• 形式
  形式有多种变化：
  •包含任何结构的概念论文
  •使用架构视图符号的切面模型摘录或场景
  •样本实现，特别是针对技术概念的实现
  •标准框架典型使用的参考（例如，使用Hibernate进行对象/关系映射）

• 结构
  本部分的潜在（但不是强制性的）结构可能包括：
  •领域概念
  •用户体验概念（UX）
  •安全与保障概念
  •架构和设计模式
  •“底层”
  •开发概念
  •运营概念

注：将个别概念分配给此清单上的特定主题可能会有困难。

请参阅arc42文档中的概念部分。

• <概念1>
  <explanation>

• <概念2>
  <explanation>
  …

• <概念n>
  <explanation>

架构决策

• 内容
  重要、昂贵、大规模或风险较高的架构决策，包括理据。通过“决策”，我们指的是根据给定标准选择一个方案。
  请自行判断应该在这个中心部分中记录哪些架构决策，或者更好地在本地记录（例如在一个构建模块的白盒模板内部）。
  避免冗余。请参考第4节，那里已经记录了架构的最重要决策。

• 动机
  您系统的利益相关者应能够理解和追溯您的决策。

• 形式
  多种选项：
  • ADR（架构决策文件）: 每个重要决策
  • 列表或表格，按重要性和后果排序，或：
  • 以每个决策为独立章节更详细地呈现

请参阅arc42文档中的Architecture Decisions。那里您将找到关于ADR的链接和示例。

质量要求

• 内容
  本节包含了作为质量树和场景的所有质量要求。其中已经在第1.2节（质量目标）中描述了最重要的要求。
  在这里，您还可以捕捉优先级较低的质量要求，当这些要求未能完全实现时不会产生较高的风险。

• 动机
  由于质量要求将对架构决策产生很大影响，您需要了解每位利益相关者对他们来说什么是真正重要的、具体和可衡量的。
  请参阅arc42文档中的质量要求。

质量树

• 内容
  根据ATAM（架构权衡分析方法）定义的质量树，其中质量/评估场景作为叶子节点。

• 动机
  树状结构及其优先级为数量庞大的质量要求提供了一个概览。

• 形式
  质量树是对质量目标和要求的高级概述：
  •“质量”一词的树状细化。使用“质量”或“有用性”作为根
  •以质量类别为主干的思维导图
  在任何情况下，树状结构应包括指向以下部分场景的链接。

质量场景

• 内容
  （有时模糊不清或隐含的）质量要求的具体化，使用（质量）场景。
  这些场景描述了系统对刺激到达时应该发生的情况。
  对于架构师，有两种场景是重要的：
  • 使用场景（也称为应用场景或用例场景）描述了系统对特定刺激的运行时反应。这还包括描述系统
  效率或性能的场景。例如：系统对用户请求的反应时间在一秒内。
  • 变更场景描述了系统或其直接环境的修改。例如：实现了额外功能或质量属性要求发生了变化。

• 动机
  场景使质量要求具体化，并且能够更容易地衡量或决定它们是否得到满足。
  特别是当您希望使用ATAM等方法评估您的架构时，您需要更精确地描述您的质量目标（来自第1.2节），
  直到可以讨论和评估的场景级别。

• 形式
  表格或自由文本。

风险和技术债务

• 内容
  已确认的技术风险或技术债务列表，按优先级排序

• 动机
  “风险管理就是成熟的项目管理”（Tim Lister, Atlantic Systems Guild。）这应该成为您在架构
  中系统性地发现和评估风险和技术债务的座右铭，这将是管理利益相关者（例如项目经理、产品负责人）作
  为整体风险分析和测量规划的一部分。

• 形式
  风险和/或技术债务清单，可能包括建议的措施以最小化、减轻或避免风险或减少技术债务。

请参阅arc42文档中的Risks and Technical Debt章节。

术语表

• 内容

  • 利益相关者讨论系统时使用的最重要的领域和技术术语。
  • 如果您在多语言团队中工作，您也可以将术语表视为翻译的来源。

• 动机
  您应该明确定义您的术语，以便所有利益相关者：
  • 对这些术语拥有相同的理解
  • 不使用同义词和同音异义词

具有列 <Term> 和 <Definition> 的表格。
如有必要，还可能存在更多列用于进行翻译。
请参阅arc42文档中的术语表。