语言 Chinese, Simplified

SEO Title

这篇文章是软件架构编年史的一部分，一系列关于软件架构的文章。在这些文章中，我写了我在软件架构学到了什么，我如何看待它，以及我如何使用这些知识。如果您阅读了本系列以前的文章，那么本文的内容可能更有意义。

我们学习如何编码，我们构建一些很酷的应用程序，然后我们学习架构，以及如何让应用程序保持数年的可维护性……

然而，当我们需要向其他人(新开发人员、产品所有者、投资者……)解释应用程序如何工作时，我们需要更多的东西……我们需要文档。

但是，我们有哪些文档选项可以表达整个应用程序构建块及其工作方式呢?

在这篇文章中，我要写的是:

UML
4+1架构视图模型
体系结构决策记录
C4模型
依赖关系图
应用程序地图

UML

我们可以使用UML创建一些图表，我们可以将它们分成两类:

行为的UML图
- 活动图
- 用例图
- 交互概览图
- 时间图
- 状态机图
- 通信图
- 序列图
结构UML图
- 类图
- 对象图
- 组件图
- 组合结构图
- 部署图
- 包图
- 概要图

我不会详细介绍每一种类型的图，因为在这篇文章中涉及的内容太多了，而且有大量的资源记录了这些图类型。要了解更多关于这些类型的信息，您可以查看上面的链接，这些链接指向一些可视化范例指南，或者查看这篇博客文章。

总之，UML很酷，很有趣，我们可以用它来表达，我们可以很容易地用它来勾画一些想法，并与同事讨论。

然而，要使用UML记录整个应用程序体系结构，我们需要使用几种类型的图。此外，如果我们试图使用单个类图来表示整个应用程序，那就麻烦了。

一个很好的使用UML类图的例子是记录设计模式:

Source: https://java-design-patterns.com/patterns/strategy

这很好，这真的很棒!它可以表达类、接口、可用性和继承关系、数据和行为。它也很简洁、易读，而且因为它很小，创建起来也很快。

然而，下面的例子不是很有用……它非常大，所以它变得混乱和难以理解。此外，创建它将花费大量的时间，当我们完成时，它可能已经过时了，因为同时有人会对代码进行更改。

Source: https://knowhow.visual-paradigm.com

因此，我们可以并且应该使用UML，但是在某些情况下应该使用它:详细描述模式、应用程序的一小部分，或者用低细节(不使用类图)描述应用程序的高粒度视图。

但接下来的问题是，我们如何记录完整的应用程序?

4+1架构视图模型

4+1架构视图模型由Philippe Kruchten创建，并在1995年发表了他的论文《架构蓝图——软件架构的4+1视图模型》。

这种可视化软件应用程序架构的方法基于应用程序的5个视图/透视图，告诉我们哪些图可以用来记录这些视图。

逻辑/结构视图

关注系统所提供的功能，以及如何设计程式以提供这些功能;

实施/开发视图

描述程式码、组件、模组及套件的静态组织;

过程/行为视图

关注系统的运行时行为、系统进程如何通信、并发、同步、性能等;

部署/物理视图

举例说明应用程序的物理组织，它是关于“什么代码在什么硬件上运行”;

用例/场景视图

整个体系结构在几个用例的帮助下得到了解释，这些用例只是交互的序列。架构的一部分是从这样的用例发展而来的。

需要注意的是，4+1架构视图模型并不要求我们使用所有提到的图，甚至不是所有的视图。我们总是需要了解工具，并使用不超过或少于我们所需要的。

体系结构决策记录

架构决策记录(ADR)实际上并不是关于记录应用程序架构当前或未来的状态，而是关于导致这种状态的原因。它们特别重要，因为它们打算告诉别人，以及我们未来的自己，为什么建筑是这样的。

ADR是一个关于已经做出的架构决策的日志条目，这些决策导致了架构现在或将来的状态。它们包含了描述架构的图表背后的原因。

首先，有一些我们需要知道的人工制品:

体系结构重要需求(ASR):对软件系统的体系结构具有可度量影响的需求;
架构决策(AD):针对重要需求的软件设计选择;
架构决策记录(ADR):捕获重要架构决策及其上下文和结果的文档;
架构决策日志(ADL):为特定项目(或组织)创建和维护的所有adr的集合;
架构知识管理(AKM):以前所有概念的更高层次。

我已经看到了一些用于创建adr的模板，并且我在其中的几个中看到了一些不错的东西，所以我创建了自己的模板。你可以，或许也应该创建一个对你和你的团队有意义的网站。

对我来说，模板最重要的一点是它很简单，它有一些文档来帮助填充它，甚至帮助做出实用的和公正的决定。

使用ADR的最佳方式不是简单地将其作为讨论和决定之后的书面文件。最好是将其作为讨论的起点，作为RFC(征求意见)，这是我们提交给团队/部门的其他成员的想法/建议，要求他们提供输入/意见/批准。其目的实际上是用它来开始讨论，进行头脑风暴，做出可能的最佳决策，并使用提案文档本身作为决策日志条目(ADR)。ADR是预先编写的这一事实并不意味着它是不可变的，它必须随着讨论的展开而更新/改进。我觉得把所有正在考虑的方案都写下来，把它们的利弊都写下来，以便引起讨论，做出明确的决定，这一点特别重要。

这就是我想到的模板:

https://docs.google.com/document/d/1Xe5erulKsdaha3uwU6tNWsAWxjQK-Rcrr_i…

可以从谷歌文档中随意复制。

如果你想进一步了解这个主题，我建议你去Joel Parker Henderson github的adr库。

C4模型

C4模型是由Simon Brown引入的，这是迄今为止我遇到的关于软件架构文档的最好的想法。我将很快地用我自己的话解释主要思想，尽管使用他自己的示例图。

这个想法是使用4种不同的粒度(或缩放)级别来记录软件架构:

级别1:系统上下文关系图
级别2:容器图
级别3:组件图
级别4:代码图

级别1:系统上下文关系图

这是最高粒度的图表。它几乎没有细节，但是它的主要目标是描述应用程序所在的上下文。因此，它将由整个应用程序的单个框组成，它将被引用应用程序与之交互的外部系统和用户的其他框包围。

级别2:容器图

现在，我们放大我们的应用程序，上图中的蓝色正方形映射到下图中的虚线正方形。

在这个粒度级别，我们将看到应用程序的容器，其中容器是应用程序的任何独立技术部分，例如移动应用程序、API或数据库。它还记录了使用的主要技术以及容器如何通信。

级别3:组件图

组件图向我们展示了一个容器中的组件。在这种情况下，每个组件都是应用程序的一个模块，不局限于域明智的模块(即。但也包括纯粹的功能模块(即。电子邮件、短信、……)。这张图向我们展示了集装箱的主齿轮以及这些齿轮之间的关系。

四级:代码

最细粒度的图，旨在描述组件内部的代码结构。对于这个级别，我们使用带有类级工件的UML图。

要了解更多，你可以在这里和这里阅读西蒙·布朗自己对它的解释，甚至在这里观看他谈论它。

还缺什么?

我认为C4模型是一种记录应用程序架构的好方法，在一定程度上理解应用程序架构是很好的，但是我仍然觉得它不够，尽管我花了一些时间来了解所缺少的内容。

在这些图表中，我看到了三个限制:

除了一些例外，比如Simon Brown的structurizr，它们需要手动生成，而不是自动生成，也不是直接从代码中提取，这意味着它们可能不会反映实际的代码，而是我们目前对它的理解;
它们并不能很好地帮助我们了解我们的应用程序代码库中存在的问题，比如混乱的代码关系和糟糕的结构，这些问题影响了对任何工程产品都至关重要的模块化和封装;
它们不能帮助我们从整体上理解我们的代码库，应用程序齿轮可以做什么，以及它们之间如何交互。

我发现了两类图表可以帮助我们。

依赖关系图

依赖关系图有助于告诉我们存在于代码库中不同类型代码中的依赖关系。

这里至关重要的一点是，这些图是直接从代码中自动生成的，否则图将只反映我们认为的代码的样子，如果这是正确的，我们就不需要这种类型的文档了。

此外，可能比图本身更重要的是，在我们的预定义依赖关系规则中断的情况下，使用这些依赖关系分析来停止构建的能力。工具用于生成这些图也应该是可用的测试工具,包括在我们的CI管道,就像单元测试,防止不必要的依赖性达到生产、维护和实施模块化,这反过来有助于达到高可变性率,因此发展高速度的功能。

在这类关系图中，我发现拥有3种不同类型的关系图很有用，可以断言不同的依赖项类型。

在下面的例子中，它们都是由deptrac为我的宠物项目(explicit-architecture-php)生成的，我使用它进行实验。您可以在存储库根中找到用于生成它们的配置。

不过，请注意，我自己添加的颜色，以使它更容易阅读这篇博客文章。颜色代表应用程序中的不同层，与我在以前的博客文章中所写的层一致:

层依赖图

此图的目的是可视化并确保每个层中的代码只能依赖于其内部或下面的层。

因此，在下面的图中我们可以看到，例如，作为最外层之一的基础结构层可以依赖于任何其他层。另一方面，域层作为顶部的中心层，只能依赖于下面的层，即SharedKernel-Domain(它也是域的一部分)和PhpExtension(它的代码被当作语言本身的一部分使用)。

类依赖关系图

层依赖关系图分析层与层之间的依赖关系，但是在层中仍然有不能发生的依赖关系。

类依赖关系图对于分析代码库中不同类型的类之间的依赖关系非常有用，特别是当它们位于同一层时。

Class dependencies diagram generated by deptrac for https://github.com/hgraca/explicit-architecture-php

组件依赖关系图

组件是一个域明智的模块，一个包含应用程序和域层的模块。例如，一个组件可以是包含所有用例和域逻辑的“计费”。

组件可以映射到DDD有界的上下文和/或微服务，这意味着它们必须在物理上和时间上与其他组件完全解耦。如果我们有一个具有完全解耦组件的单片应用程序，那么将其转换为微服务体系结构将是相当容易的(在代码方面)。

此外，将相同的解耦需求应用于其他非域明智模块，我们可以保证可以轻松替换任何模块。

组件依赖关系图的目的是确保应用程序组件和模块是解耦的。

请注意，在下面的图表中，同一层中的模块(具有相同颜色的节点)都不知道彼此，至少是直接不知道。

特别重要的是，这两个组件(用户和博客，中蓝色)是解耦的。如果这个应用程序有一个微服务体系结构，那么这两个组件就是微服务。

Component dependencies diagram generated by deptrac for https://github.com/hgraca/explicit-architecture-php

应用程序地图

大约一年前,我意识到别的我还缺少这些文档中选择:所有这些图,他们告诉我们什么是应用程序的构建块,哪些块相互作用以及它们之间的关系,但是他们不告诉我们他们所做的,也不是当他们如何相互影响。为此，我们需要从用户的角度非常了解应用程序，或者从开发人员的角度了解代码库。前面的图没有告诉我们在应用程序中有什么用例，也没有告诉我们什么用例触发了什么事件，也没有告诉我们这些事件的结果。如果我们将这些图显示给产品负责人，他会发现这些图对他的角色几乎毫无用处。

所以我想到了一个新的文档图的想法，我称之为应用程序映射，它可以替代C4模型组件图。

应用程序地图的目标是成为真正的应用程序地图，定义它的“城市”(组件)、“本地道路”(用例)、“高速公路”(事件)等等。

模块和组件之间的区别是，模块是应用程序的任何模块，而组件是应用程序的域模块。因此，虽然ORM是应用程序的模块，但它不是组件，因为它只处理技术问题。另一方面，“计费”模块是一个组件，因为它处理域问题。

应用程序映射首先定义应用程序的组件，域明智的模块，如“账单”、“用户”、“公司”、“订单”、“产品”等。对于一个简单的博客应用程序，我们可以有两个组件，“用户”和“博客”组件:

在每个组件中，我们定义可以向它们发出的命令。“用户”组件可以创建和删除用户，而“博客”组件可以创建和删除帖子，并创建对帖子的评论。