本文永久链接 – https://tonybai.com/2024/01/01/go-testing-by-example

2023年11月初，Go语言技术负责人Russ Cox在GopherCon Australia 2023大会上进行了题为“Go Testing By Example”的演讲：

12月初Russ Cox重新录制了该演讲内容的视频，并在个人网站上放了出来。这个演讲视频是关于如何编写好的Go测试的，Russ Cox介绍了20个实用建议，非常值得Go初学者甚至Go资深开发者学习并应用到实践中。这里是基于该视频整理的文字稿(可能并非逐字逐句)，供广大Gopher参考。

注：在GopherCon Australia 2023，退休后暂定居澳大利亚的Go语言之父Rob Pike也做了一个名为“What We Got Right, What We Got Wrong”的主题演讲。在Go开源14年之后，有很多事情值得思考。这个演讲“事后诸葛亮般地”探讨了Go迄今为止取得的一些经验教训：不仅包括进展顺利的方面，还包括本可以做得更好的方面。可惜目前该演讲视频或文字稿并未放出，我们也只能等待。

大家好！这是几周前我在GopherCon Australia 2023进行的一次演讲，演讲的内容是关于如何编写好的测试。

不过首先让我们来思考一下为什么我们要编写测试。一些有关编程的书中常讲到：测试是为了发现程序中的错误！比如Brian W. Kernighan和Rob Pike合著的《The Practice of Programming》一书中讲到：“测试是一种坚定的、系统地尝试，旨在破坏你认为可以正确运行的程序”。这是真实的。这就是为什么程序员应该编写测试。但对于今天在这里的大多数人来说，这不是我们编写测试的原因，因为我们不仅仅是程序员，我们是软件工程师。什么意思呢？我想说的是，软件工程就是当你编程时增加时间和其他程序员时所发生的事情。编程意味着让程序运行，你有一个问题需要解决，你编写一些代码，运行它，测试它，调试它，得到答案，你就完成了。这本已经相当困难了，而测试是该过程的重要组成部分。但软件工程意味着你在长期与其他人一起开发的程序中完成所有这些工作，这改变了测试的性质。

让我们先看一个对二分查找函数的测试：

如图所示，这个函数接受一个有序(sorted)切片、一个目标值(target)和一个比较函数(cmp)。它使用二分搜索算法查找并返回两个内容：第一，如果目标存在，则返回其索引(index)，第二是一个布尔值，指示目标是否存在。

大多数二分查找算法的实现都有错误，这个也不例外。我们来测试一下。

下面是一个很好的二分搜索的交互式测试：

你输入两个数字n和t，测试程序便创建一个包含n个元素的切片，其元素值按10倍增，然后程序在切片中搜索t并打印结果，然后你反复重复这一过程。

这可能看起来不足为奇，但有多少人曾经通过运行这种交互式测试程序来测试生产环境用的代码(production code)？我们所有人都这样做过。当你独自编程时，像这样的交互式测试程序对于查找bug非常有用，到目前为止代码看起来可以正常工作。

但这个交互式测试程序只适合独自编程时使用，如果你从事软件工程，意味着你要长时间保持程序的运行，并与其他人合作，那么这种类型的测试程序就不太有用了。

你需要一种每个人都可以在日常工作中运行的测试程序，可以在他们编写代码的同时运行，并且可以由计算机在每次代码提交时自动运行。问题在于仅通过手动测试程序只能确保它在今天正常工作，而自动化、持续的测试可以确保它在明天和未来都可以正常工作，即使其他不熟悉这段代码的人开始对其进行维护。并且我们要明确一点：那个不太熟悉代码的人可能是指未来六个月甚至六周后的你。

这是一个软件工程师的测试。你可以在不了解代码工作原理的情况下运行它。任何同事或任何计算机都可以使用”go test”运行该测试，并可以立即知道该测试是否通过。我肯定你已经见过这样的测试了。

软件工程的理想是拥有能够捕捉到后续可能出现的所有错误的测试。如果你的测试达到了这个理想状态，那么当你的所有测试都通过时，你应该可以放心地自动将你的代码部署到生产环境中，这就是人们所称的持续部署。如果你还没有这样做，如果这个想法让你感到紧张，那么你应该问问自己为什么。要么你的测试已经足够好，要么它们还不够好。如果它们足够好，那为什么不这样做呢？而如果它们不够好，那就倾听这些疑虑，并找出它们告诉你哪些测试被遗漏了。

几年前，我正在为新的Go官方网站go.dev编写代码。那时我们还在手动部署该网站，并且至少每周一次。我做的一项代码变更在我的机器上运行正常，但在部署到生产环境后便无法正常工作了，这着实令人非常烦恼和尴尬。解决办法是进行更好的测试和自动化的持续部署。现在，每当代码库中有新的提交时，我们使用一个Cloud Build程序来运行本地测试，并将代码推送到一个全新的服务器，然后运行一些只能在生产环境中运行的测试。如果一切正常，我们会将流量打到新的服务器。这样做改善了两点。首先，我不再导致令人尴尬的网站宕机。其次，每个人都不再需要考虑如何部署网站。如果他们想做变更，比如修复拼写错误或添加新的博客文章，他们只需发送更改请求，对其进行审核、测试和提交，然后自动化流程会完成其余工作。

要确信当其他人更改代码时你的程序不会出错，要确信只要测试通过就可以随时将程序推送到生产环境，你需要一套非常好的测试。但是什么样的测试才算是好的呢？

一般来说，使测试代码优秀的因素与使非测试代码优秀的因素是相同的：勤奋(hard work)、专注(attention)和时间(time)。对于编写优秀的测试代码，我没有什么“银弹式”的或硬性的规则，就像编写优秀的非测试代码一样。然而，我确实有一系列基于我们在Go上的良好实践的建议，我将在这次演讲中分享20个编写优秀测试代码的实用建议。

建议1：让添加新测试用例变得容易

这是最重要的建议。因为如果添加一个新测试用例很困难，你就不会去做。在这方面，Go已经提供了很好的支持。

上图是函数Foo的一个最简单的测试。我们专门设计了Go测试，使其非常容易编写。没有繁杂的记录或仪式会妨碍你。在包级别的测试中，这已经相当不错了，但在特定的包中，你可以做得更好。

我相信你已经了解了表驱动测试。我们鼓励使用表驱动测试，因为它们非常容易添加新的测试用例。这是我们之前看到的那个测试用例：假设我们只有这一个测试用例，然后我们想到了一个新的测试用例。我们根本不需要编写任何新的代码，只需要添加一行新的数据。如果目标是“使添加新的测试用例变得容易”，那么对于像这样的简单函数，向表中添加一行数据就足够了。不过，这也引出了一个问题：我们应该添加哪些测试用例？这将引导我们来到下一个建议。

建议2：使用测试覆盖率来发现未经测试的代码

毕竟，测试无法捕捉到未运行的代码中的错误。Go内置了对测试覆盖率的支持。下面是它的样子：

你可以运行“go test -coverprofile”来生成一个覆盖率文件，然后使用“go tool cover”在浏览器中查看它。在上图的显示中，我们可以看到我们的测试用例还不够好：实际的二分查找代码是红色的，表示完全未经测试。下一步是查看未经测试的代码，并思考什么样的测试用例会使这些代码行运行。

经过仔细检查，我们只测试了一个空切片，所以让我们添加一个非空的切片的测试用例。现在我们可以再次运行覆盖率测试。这次我将用我写的一个小命令行程序“uncover”来读取覆盖率文件。Uncover会显示未被测试覆盖的代码行。它不会给你网页视图那样的全局视图，但它可以让你保持在一个终端窗口中。Uncover向我们展示了只剩下一行代码未被测试执行。这是进入切片的第二半部分的行，这是有道理的，因为我们的目标是第一个元素。让我们再添加一个测试，搜索最后一个元素。

当我们运行测试时，它通过了，我们达到了100%的覆盖率。很棒。我们完成了吗？没有，这将引导我们到下一个实用建议。

建议3：覆盖率不能替代思考

覆盖率对于指出你可能忽略的代码部分非常有用，但机械工具无法替代对于高难度的输入、代码中的微妙之处以及可能导致代码出错的情况进行的实际思考。即使代码拥有100%的测试覆盖率，仍然可能存在bug，而这段代码就存在bug。这个提示也适用于覆盖率驱动的模糊测试(fuzzing test)。模糊测试只是尝试通过代码探索越来越多的路径，以增加覆盖率。模糊测试也非常有帮助，但模糊测试也不能替代思考。那么这里缺少了什么呢？

需要注意的一点是，唯一一个无法找到目标的测试用例是一个空输入切片。我们应该检查在具值的切片中无法找到目标的情况。具体来说，我们应该检查当目标小于所有值、大于所有值和位于值的中间时会发生什么。所以让我们添加三个额外的测试用例。

注意添加新测试用例是多么容易。如果你想到一个你的代码可能无法正确处理的情况，添加该测试用例应该尽可能简单，否则你就会觉得麻烦而不去添加。如果太困难，你就不会添加。你还可以看到我们正在开始列举这个函数可能出错的所有重要路径。这些测试对未来的开发进行了约束，以确保二分查找至少能够正常工作。当我们运行这些测试时，它们失败了。返回的索引i是正确的，但表示target是否找到的布尔值是错误的。所以让我们来看看这个问题。

阅读代码，我们发现返回语句中的布尔表达式是错误的。它只检查索引是否在范围内。它还需要检查该索引处的值是否等于target值。所以我们可以进行这个更改，如图所示，然后测试通过了。现在我们对这个测试感到非常满意：覆盖率是良好的，我们也经过了深思熟虑。还能做什么呢？

建议4：编写全面的测试

如果你能够测试函数的每一个可能输入，那就应该这样做。但现实中可能无法做到，但通常你可以在一定约束条件下测试特定数量以内的所有输入。下面是一个二分查找的全面测试：

我们首先创建一个包含10个元素的切片，具体来说就是从1到19的奇数。然后我们考虑该切片的所有可能长度的前缀。对于每个前缀，我们考虑从0到两倍长度的所有可能目标，其中0是小于切片中的所有值，两倍长度是大于切片中的所有值。这将详尽地测试每个可能的搜索路径，以及长度不超过我们的限制10的所有可能尺寸的切片。但是现在我们怎么知道答案是什么呢？我们可以根据测试用例的具体情况进行一些数学计算，但有一种更好、更通用的方法。这种方法是编写一个与真正实现不同的参考实现。理想情况下，参考实现应该明显是正确的，但它只需与真实实现采用不同的方法即可。通常，参考实现将是一种更简单、更慢的方法，因为如果它更简单和更快，你会将其用作真正的实现。在这种情况下，我们的参考实现称为slowFind。测试检查slowFind和Find是否可以在答案上达成一致。由于输入很小，slowFind可以采用一个简单的线性搜索。

通过生成所有可能的输入并将结果与简单的参考实现进行比较，这种模式非常强大。它做的一件重要的事情是覆盖了所有基本情况，例如0个元素的切片、1个元素的切片、长度为奇数的切片、长度为偶数的切片、长度为2的幂的切片等等。大多数程序中的绝大多数错误都可以通过小规模的输入进行重现，因此测试所有小规模的输入非常有效。事实证明，这个全面测试通过了。我们的思考相当不错。

现在，如果全面测试失败，那意味着Find和slowFind不一致，至少有一个有bug，但我们不知道是哪一个有问题。添加一个直接测试slowFind会有所帮助，而且很容易，因为我们已经有了一个测试数据表。这是表驱动测试的另一个好处：可以使用这些表来测试多个实现。

建议5：将测试用例与测试逻辑分开

在表驱动测试中，测试用例在表中，而处理这些测试用例的循环则是测试逻辑。正如我们刚才所看到的，将它们分开可以让你在多个上下文中使用相同的测试用例。那么现在我们的二分查找函数完成了吗？事实证明没有，还有一个bug存在，这引导我们到下一个问题。

建议6：寻找特殊情况

即使我们对所有小规模情况进行了全面测试，仍然可能存在潜在的bug：

现在，这里再次展示了代码。还剩下一个bug。你可以暂停视频，花一些时间来查看它。

有人看出bug在哪里了吗？如果你没有看到，没关系。这是一个非常特殊的情况，人们花了几十年的时间才注意到它。Knuth告诉我们，尽管二分查找在1946年发表，但第一个正确的二分查找实现直到1964年才发表。但是这个bug直到2006年才被发现。

bug是这样的，如果切片中的元素数量非常接近int的最大值，那么i+j会溢出，因此i+j/2就不是切片中间位置的正确计算方法了。这个bug于2006年在一个使用64位内存和32位整数的C程序中被发现，这个程序用于索引包含超过10亿个元素的数组。在Go语言中，这种特定组合基本上不会发生，因为我们要求使用64位内存时，也要使用64位整数，这正是为了避免这种bug。但是，由于我们了解到这个bug，而且你永远不知道你或其他人将来如何修改代码，所以避免这个bug是值得的。

有两种常见的修复方法可以避免数学计算溢出。速度稍快的方法是进行无符号除法。假设我们修复了这个问题。现在我们完成了吗？不。因为我们还没有编写测试。

建议7：如果你没有添加测试，那就没有修复bug

这句话在两个不同的方面下都是正确的。

第一个是编程方面。如果你没有进行测试，bug可能根本没有被修复。这听起来可能很愚蠢，但你有多少次遇到过这种情况？有人告诉你有一个bug，你立即知道修复方法。你进行了更改，并告诉他们问题已经修复。然后他们却回来告诉你，不，问题还存在。编写测试可以避免这种尴尬。你可以说，很抱歉我没有修复你的bug，但我确实修复了一个bug，并会再次查看这个问题。

第二个是软件工程方面，即“时间和其他程序员”的方面。bug并不是随机出现的。在任何给定的程序中，某些错误比其他错误更有可能发生。因此，如果你犯了一次这个错误，你或其他人很可能在将来再次犯同样的错误。如果没有测试来阻止它们，bug就会重新出现。

现在，这个特定的测试很难编写，因为输入范围非常大，但即使测试很难编写，这个建议仍然成立。实际上，在这种情况下，这个建议通常更为正确。

为了测试这种情况，一种可能性是编写一个仅在32位系统上运行的测试，对两千兆字节的uint8进行二分查找。但这需要大量的内存，并且我们现在已经没有多少32位系统了。对于测试这种难以找到的bug，通常还有更巧妙的解决方案。我们可以创建一个空结构体的切片，无论它有多长，都不会占用内存。这个测试在一个包含MaxInt个空结构体的切片上调用Find函数，寻找一个空结构体作为目标，但是它传入了一个总是返回-1的比较函数，声称切片元素小于目标。这将使二分查找探索越来越大的切片索引，从而导致溢出问题。如果我们撤销我们的修复并运行这个测试，那么测试肯定会失败。

而使用了我们的修复后，测试通过了。现在bug已经修复了。

建议8：并非所有东西都适合放在表中

这个特殊情况不适合放在表中，但这没关系。但是很多东西确实适合放在表中。

这是我最喜欢的一个测试表之一。它来自fmt.Printf的测试用例。每一行都是一个printf格式、一个值和预期的字符串。真实的表太大了，无法放在幻灯片上，但这里摘录了一些表中的代码行。

如果你仔细阅读整个表，你会看到其中一些明显是修复bug的内容。记住建议7：如果你没有添加测试，那就没有修复bug。表格使得添加这些测试变得非常简单，并且添加这些测试可以确保这些bug不会再次出现。

表格是将测试用例与测试逻辑分离并且方便添加新的测试用例的一种方法，但有时你会有很多测试，甚至写Go语法的开销也是不必要的。例如，这里是strconv包的一个测试文件，用于测试字符串与浮点数之间的转换。你可能认为编写解析器来处理这个输入太麻烦了，但一旦你知道了如何处理，其实并不需要太多工作，而且定义测试专用的小型语言实际上非常有用。

因此，我将快速介绍一下解析器，以展示它并不复杂。我们读取文件，然后将其分割成行。对于每一行，我们计算错误消息的行号。切片元素0表示第1行。我们去掉行尾的任何注释。如果行为空白行，我们跳过它。到目前为止，这是相当标准的样板代码。现在是重点。我们将行分割为字段，并提取出四个字段。

然后根据类型字段在float32或float64的数学运算中进行转换。myatof64基本上是strconv.ParseFloat64的变体，不同之处在于它处理允许我们按照从论文中复制的方式编写测试用例的十进制p格式。

最后，如果结果不是我们想要的，我们打印错误。这非常类似于基于表格的测试。我们只是解析文件，而不是遍历表格。它无法放在一个幻灯片上，但在开发时它可以放在一个屏幕上。

建议9：测试用例可以放在testdata文件中

测试不必都要放在源代码中。

作为另一个例子，Go正则表达式包包含了一些从AT&T POSIX正则表达式库复制过来的testdata文件。我不会在这里详细介绍，但我很感激他们选择为该库使用基于文件的测试，因为这意味着我可以重用testdata文件，将其用于Go。这是另一种ad-hoc格式，但它易于解析和编辑。

建议10：与其他实现进行比较

与AT&T正则表达式的测试用例进行比较有助于确保Go的包以完全相同的方式处理各种边缘情况。我们还将Go的包与C++的RE2库进行比较。为了避免需要编译C++代码，我们以记录所有测试用例的方式运行它，并将该文件作为testdata提交到Go中。

在文件中存储测试用例的另一种方法是使用成对的文件，一个用于输入，一个用于输出。为了实现go test -json，有一个名为test2json的程序，它读取测试输出并将其转换为JSON输出。测试数据是成对的文件：测试输出和JSON输出。

这是最简短的文件。测试输出位于顶部，它是test2json的输入，应该生成底部的JSON输出。以下是实现，展示了从文件中读取测试数据的惯用方法。

我们首先使用filepath.Glob查找所有的testdata。如果失败或找不到任何文件，我们会报错。否则，我们循环遍历所有文件。对于每个文件，我们通过获取基本文件名（不包括testdata/目录名和文件后缀）来创建子测试名称。然后我们用该名称运行一个子测试。如果你的测试用例足够复杂，每个文件一个子测试通常是有意义的。这样，当一个测试用例失败时，你可以使用go test -run只运行特定的文件。

对于实际的测试用例，我们只需要读取文件，运行转换器，并检查结果是否匹配。对于检查，我最开始使用了bytes.Equal，但随着时间的推移，编写一个自定义的diffJSON函数来解析两个JSON结果并打印实际差异的详细说明变得更有价值。

建议11：使测试失败易读

回顾一下，我们已经在二分查找中看到了这一点。

我认为我们都同意粉色框不是一个好的失败。但是黄色框中有两个细节使得这些失败尤为出色。首先，我们在单个if语句中检查了两个返回值，然后在简洁的单行中打印了完整的输入和输出。其次，我们不会在第一个失败处停止。我们使用t.Error而不是t.Fatal，以便执行更多的测试用例。结合起来，这两个选择让我们可以看到每个失败的完整细节，并在多个失败中寻找模式。

回到test2json，这是它的测试失败的情况。它计算出哪些事件是不同的，并清晰地标记它们。重要的是，在你编写测试时，你不必写这种复杂的代码。bytes.Equal在开始时是可以的，并且可以专注于代码。但是随着失败变得更加微妙，并且你发现自己花费太多时间只是阅读失败输出，这是一个好的信号，它告诉你是时候花一些时间使其更易读了。此外，如果确切的输出发生更改并且你需要更正所有的测试数据文件，这种类型的测试可能会有点麻烦。

建议12：如果答案可能会改变，编写代码来更新它们

通常的做法是在测试中添加一个“-update”标志。这是test2json的更新代码示例。

测试定义了一个新的“-update标志”。当标志为true时，测试将计算的答案写入答案文件，而不是调用diffJSON。现在，当我们对JSON格式进行有意的更改时，“go test -update”会更新所有答案。你还可以使用版本控制工具如“git diff”来审查更改，并在看起来不正确时撤销更改。在谈论测试文件的主题上，有时将一个测试用例分割成多个文件会很烦人。如果我今天编写这个测试，我就不会这样做。

建议13： 使用txtar进行多文件测试用例

注：导入txtar：import “golang.org/x/tools/txtar”

Txtar是我们几年前专门为解决多文件测试用例问题而设计的一种新的存档格式。其Go解析器位于golang.org/x/tools/txtar中，我还找到了用Ruby、Rust和Swift编写的解析器。

Txtar的设计有三个目标。首先，足够简单，可以手动创建、编辑和阅读。其次，能够存储文本文件的树形结构，因为我们在go命令中需要这个功能。第三，能够在git历史记录和代码审查中进行良好的差异比较。其他的包括成为完全通用的存档格式、存储二进制数据、存储文件模式(file mode)、存储符号链接等都不是目标，因为存档文件(archived file)格式往往变得十分复杂，而复杂性与第一个目标直接相矛盾。这些目标和非目标导致了一个非常简单的格式。下面是一个示例：txtar文件以注释开头。

本例中为”Here are some greetings.”，然后通常会有零个或多个文件，每个文件由形如”– 文件名 –”的行引入。这个存档包含两个单行文件，hello和g’day。就是这样，这就是整个格式。没有转义，没有引用，没有对二进制数据的支持，没有符号链接，没有可能的语法错误，没有复杂之处。下面是一个在测试数据中使用txtar文件的真实示例。

该测试数据用于计算差异的包：在这种情况下，注释对于人们来说很有用，用于记录正在进行的测试，然后在这个测试中，每个用例由两个文件和它们的差异后面跟随的两个文件组成。

使用txtar文件几乎和编写它们一样简单。下面是我们之前查看的diff包的测试。

这是通常的基于文件的循环，但我们在文件上调用了txtar.ParseFile。然后我们坚持认为存档包含三个文件，第三个文件的名称为diff。然后我们对两个输入文件进行差异比较，并检查结果是否与预期的差异匹配。

这就是整个测试。你可能已经注意到，在使用之前，文件数据会被传递给”clean”函数进行清理。clean函数允许我们在不使txtar格式本身复杂化的情况下添加一些特定于diff的扩展。

第一个扩展处理以空格结尾的行，在差异中确实会出现这种情况。许多编辑器希望去除这些尾随空格，因此测试允许在txtar的数据行末尾放置$，并且clean函数会删除该$。在这个示例中，标记的行需要以一个空格结尾。

此外，txtar要求文件中的每一行都以换行符结尾，但我们希望测试diff在不以换行符结尾的文件上的行为。因此，测试允许在结尾处放置一个字面意义上的“尖号D”。clean函数会删除“尖号D”和其后的换行符。在这种情况下，’new’文件最终没有最后的换行符，而diff正确报告了这一点。因此，尽管txtar非常简单，你也可以轻松地在其上添加自己的格式调整。当然，重要的是要记录这些调整，以便下一个参与测试的人能够理解它们。

建议14：对现有格式进行注解(annotation)来创建测试迷你语言

对现有格式进行注释，比如在txtar中添加$和尖号D，是一个强大的工具。

这里是对现有格式进行注释的一个示例。这是Go类型检查器(type checker)的一个测试。这是一个普通的Go输入文件，但是期望的类型错误已经以/*ERROR*/注释的形式添加了进去。我们使用/*注释，这样我们就可以将它们放置在错误报告的确切位置上。测试运行类型检查器，并检查它是否在预期位置产生了预期的消息，并且没有产生任何意外的消息。下面是类型检查器的另一个示例。

在这个测试中，我们在通常的Go语法之上添加了一个assert注释。这使我们能够编写常量算术的测试，就像这个例子一样。类型检查器已经计算了每个常量表达式的布尔值，所以检查assert其实只是检查常量是否被求值为true。下面是另一个带有注释的格式示例。

Ivy是一个交互式计算器。你输入程序，通常是简单的表达式，它会打印出答案。测试用例是看起来像这样的文件：未缩进的行是Ivy的输入，缩进的行是注释，指示Ivy应该打印出预期的输出。编写新的测试用例再也没有比这更简单的了。这些带注释的格式扩展了现有的解析器和打印器(printer)。有时编写自己的解析器和打印器是有帮助的。毕竟，大多数测试涉及创建或检查数据，当你可以使用方便的形式处理数据时，这些测试总是可以更好。

建议15：编写解析器和打印器来简化测试

这些解析器和打印器不一定是用于testdata中数据文件的独立脚本。你也可以在常规的Go代码中使用它们。

这是一个运行deps.dev代码的一个测试片段。这个测试设置了一些数据库表行。它调用了一个使用数据库并正在进行测试的函数。然后它检查数据库是否包含了预期的结果。Insert和Want调用使用了一个专门为这些测试编写的用于数据库内容的迷你语言。解析器就像它看起来的那样简单：它将输入分割成行，然后将每行分割成字段。第一行给出了列名。就是这样。这些字符串中的确切间距并不重要，但是如果它们都对齐，当然看起来更美观。

因此，为了支持这个测试，deps.dev团队还有一个专门为这些测试编写的代码格式化程序。它使用Go标准库解析测试源代码文件。然后它遍历Go语法树，查找Insert或Want的调用。它提取字符串参数并将它们解析为表格。然后它将表格重新打印为字符串，将字符串重新插入语法树中，并重新打印语法树为Go源代码。这只是gofmt的一个扩展版本，使用了与gofmt相同的包。我这里不会展示这些代码，但代码量其实不多。

解析器和打印器需要花费了一些时间来编写。但现在，每当有人编写一个测试时，编写测试就更容易了。每当一个测试失败或需要更新时，调试也更容易了。如果你正在进行软件工程，收益将随着程序员数量和项目生命周期的增加而扩大。对于deps.dev来说，已经花费在这个解析器和打印器上的时间已经多次节省了。或许更重要的是，因为测试更容易编写，你可能会写更多的测试，这将导致更高质量的代码。

建议16：代码质量受测试质量限制

如果你不能编写高质量的测试，你将无法编写足够的测试，并且最终无法得到高质量的代码。

现在我想向你展示一些我曾经参与的最高质量的测试，这些测试是针对go命令的测试。它们将我们到目前为止看到的许多思想汇集在一起。这是一个简单但真实的go命令测试。这是一个txtar输入，其中包含一个名为hello.go的文件。archive comment是一个逐行简单命令语言编写的脚本。在脚本中，”env”设置一个环境变量来关闭Go module机制。井号引入注释。而”go”运行go命令，它应该运行hello world。该程序应该将hello world打印到标准错误中。”stderr”命令检查前一个命令打印的标准错误流是否与正则表达式匹配。因此，这个测试运行”go run hello.go”并检查它是否将hello world打印到标准错误中。

这里是另一个真实的测试。请注意底部的a.go是一个无效的程序，因为它导入了一个空字符串。第一行开头的感叹号是一个”非”操作符。NOT go list a.go意味着go list a.go应该失败。下一行的”NOT stdout .”表示标准输出不应该有与正则表达式”.”匹配的内容，也就是不应该打印任何文本。接下来，标准错误流应该有一个无效的导入路径的消息。最后，不应该发生panic。

建议17：使用脚本可以编写很好的测试

这些脚本使添加新的测试用例变得非常容易。

这是我们最小的测试用例：两行代码。最近我在破坏了unknown command的错误消息后添加了这个测试用例。总共，我们有超过700个这样的脚本测试，从两行到500多行不等。

这些测试脚本取代了一个更传统的使用方法(method)的测试框架。这张幻灯片展示了其中一个真实的测试，前面是脚本编写的测试用例，后面是等价的Go编写的传统测试代码。细节并不重要，只需注意脚本要比传统测试方法更容易编写和理解。

建议18：尝试使用rsc.io/script来创建基于脚本的测试用例

距离我们创建go脚本测试已经过去了大约五年时间，我们对这个特定的脚本引擎非常满意。Bryan Mills花了很多时间为它提供了一个非常好的API，早在11月份，我将其发布到了rsc.io/script以供导入使用。现在我说”尝试”是因为它还比较新，并且具有讽刺意味的是，它本身的测试还不够多，因为可导入的包只有几周的历史，但你仍然可能会发现它很有用。当我们对其有更多经验时，我们可能会将其放在更官方的位置上。如果你尝试了它，请告诉我结果如何。

提取脚本引擎的动机是为了在go命令测试的不同部分中重用它。这个脚本正在准备一个包含我们想要在常规go命令脚本测试中导入的模块的Git存储库(repo)。你可以看到它设置了一些环境变量，运行了真正的git init，设置了时间，在存储库中运行了更多的git命令来添加一个hello world文件，然后检查我们得到了我们想要的存储库。再一次，测试并不是从一开始就是这样的，这引出了下一个实用建议。

建议19：随着时间的推移改进你的测试

最初，我们没有这些存储库脚本。我们手工创建小型测试存储库，并将它们发布到GitHub、Bitbucket和其他托管服务器，具体取决于我们所需的版本控制系统。这种方法还算可以，但这意味着如果这些服务器中的任何一个宕机，测试就会失败。最终，我们花时间构建了自己的云服务器，可以为每个版本控制系统提供存储库服务。现在，我们手工创建存储库，将其压缩并复制到服务器上。这样做更好，因为现在只有一个服务器可能会使我们的测试失败，但有时也会出现网络问题。测试存储库本身也没有进行版本控制，并且与使用它们的测试不在一起，这也是一个问题。作为测试的一部分，基于脚本的版本完全可以在本地构建和提供这些存储库。而且现在很容易找到、更改和审查存储库的描述。这需要很多基础设施，但也测试了很多代码。如果你只有10行代码，你完全不需要拥有数千行的测试框架。但是如果你有十万行代码，这大约是go命令的规模，那么开发几千行代码来改进测试，甚至是一万行代码，几乎可以肯定是一个不错的投资。

建议20：追求持续部署

也许出于策略原因，你无法每次都实际部署那些通过了所有测试的代码提交，但无论如何都要追求这一目标。正如我在演讲开始时提到的，对于持续部署的任何疑问都是有益的小声音，它们告诉你需要更好的测试。而更好的测试的关键当然是让添加新测试变得容易。即使你从未实际启用持续部署，追求这一目标也可以帮助你保持诚实，提高测试的质量和代码的质量。

我之前提到过Go官方网站使用了持续部署。在每次提交时，我们运行测试来决定是否可以部署最新版本的代码并将流量路由到它。此时，你不会感到惊讶，我们为这些测试编写了一个测试脚本语言。上图是它们的样子。每个测试以一个HTTP请求开始。这里我们GET主页go.dev。然后对响应进行断言。每个断言的形式为”字段(field)，运算符(operator)，值(value)”。这里字段(field)是body，运算符(operator是contains，值(value)是body中必须包含的字面值。这个测试检查页面是否渲染过了，因此它检查基本文本以及一个副标题。为了更容易编写测试，根本没有引号。值就是运算符后面的其余部分。接下来是另一个测试用例。出于历史原因，/about需要重定向到pkg.go.dev。

这是另一个案例。这里没有什么特别的，只是检查案例研究页面是否渲染(rendering)了，因为它是由许多其他文件合成的。测试可以检查的另一个字段是HTTP响应代码，这是一个错误修复。我们错误地在Go存储库根目录中提供了这些文件，就好像它们是Go网站页面一样。我们希望改为返回404。你还可以测试标头foo的值，其中foo是某个标头。在这种情况下，标头Content-Type需要正确设置为主博客页面及其JSON feed。

这是另一个示例。这个示例使用正则表达式匹配运算符tilde和“\s+”语法，以确保页面具有正确的文本，无论单词之间有多少空格。这变得有点老套了，所以我们添加了一个名为trimbody的新字段，它是将所有空格序列替换为单个空格后的body。这个示例还显示了值可以作为多个缩进的行提供，以便更容易进行多行匹配。

我们还有一些无法在本地运行但在生产环境中仍值得运行的测试，因为我们将实时流量迁移到服务器之前需要进行这些测试。下面是其中两个。这些依赖于对生产环境playground后端的网络访问。这些案例除了URL不同之外都是相同的。这不是一个非常易读的测试，因为这些是我们唯一的POST测试。如果我们添加了更多这样的测试，我可能会花时间使它们看起来更好，以随着时间推移改进你的测试。但是现在它们还可以，它们起到了重要的作用。

最后，和往常一样，添加错误修复很容易。在问题51989中，live web站点根本没有呈现。因此，这个测试检查页面确实呈现并包含一个独特的文本片段。问题51989不会再次发生，至少不会在实际的网站上。肯定会有其他错误，但那个问题已经彻底解决了，这就是进步。以上这些是我有时间向你展示的这些例子。

小结

最后一个想法。我相信你经历过追踪错误并最终发现一个重要的代码片段是错误的情况。但不知何故，这个代码片段的错误大部分时间都无关紧要，或者错误被其他错误的代码抵消了。你可能会想：“这段代码以前是怎么工作的？”如果是你自己编写的代码，你可能会认为自己很幸运。如果是别人编写的代码，你可能会对他们的能力产生质疑，然后又认为他们很幸运。但是，大多数时候，答案并不是运气。对于这段代码为什么会工作的问题的答案几乎总是：因为它有一个测试。当然，代码是错误的，但测试检查了它足够正确，使系统的其他部分可以正常工作，这才是最重要的。也许编写这段代码的人确实是一个糟糕的程序员，但他们是一个优秀的软件工程师，因为他们编写了一个测试，这就是为什么包含该代码的整个系统能够工作的原因。

我希望你从这次演讲中得出的结论不是任何特定测试的具体细节，尽管我希望你可以留意对小型解析器和打印机的良好使用带来的好处。任何人都可以学会编写它们，并且有效地使用它们可以成为软件工程的超能力。最终，这对这些软件包来说是好测试。对于你的软件包，好测试可能看起来会有所不同。这没关系。但要使添加新的测试用例变得容易，并确保你拥有良好、清晰、高质量的测试。请记住，代码质量受测试质量的限制，因此逐步投入改进测试。你在项目上工作的时间越长，你的测试就应该变得越好。并且要追求持续部署，至少作为一种思想实验，以了解哪些方面的测试还不够充分。

总的来说，要像编写优秀的非测试代码一样，思考并投入同样的思想、关心和努力来编写优秀的测试代码，这绝对是值得的。

“Gopher部落”知识星球旨在打造一个精品Go学习和进阶社群！高品质首发Go技术文章，“三天”首发阅读权，每年两期Go语言发展现状分析，每天提前1小时阅读到新鲜的Gopher日报，网课、技术专栏、图书内容前瞻，六小时内必答保证等满足你关于Go语言生态的所有需求！2023年，Gopher部落将进一步聚焦于如何编写雅、地道、可读、可测试的Go代码，关注代码质量并深入理解Go核心技术，并继续加强与星友的互动。欢迎大家加入！

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：

• 微博(暂不可用)：https://weibo.com/bigwhite20xx
• 微博2：https://weibo.com/u/6484441286
• 博客：tonybai.com
• github: https://github.com/bigwhite
• Gopher Daily归档 – https://github.com/bigwhite/gopherdaily

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

本文永久链接 – https://tonybai.com/2023/12/06/a-minimum-set-of-diagrams-for-expressing-software-architecture

无论你是专职的软件架构师，还是在团队内兼职充当软件架构师角色的开发人员，一旦你处在软件架构师这个位置上，你自然就会遇到软件架构设计的三个困惑：

• 如何更深刻地理解业务；
• 如何更正确地取舍(包括技术性和业务性的)；
• 如何更有效地表达软件架构。

以上每个困惑展开来写都够写一本书的。而在这篇文章中，我仅聚焦最后一个困惑，聊聊我心目中表达软件架构的有效方式 — 最小图集(Minimum Diagram Set)。

1. 为什么软件架构需要有效表达

众所周知，软件架构承载着系统关键的技术决策和业务约束，指导着复杂软件的构建与演进，是实现软件系统的蓝图。但并不是说有了好的软件架构就一定可以做出好的软件系统，软件系统最终还是要经由开发人员来实现。

如果说架构师是软件架构的生产者，那么开发人员可以理解为是软件架构的消费者。但和一件普通商品一样，往往消费者很难Get到产品设计者的全部idea，产品越复杂，消费者Get到的比例越低，于是商品的生产者就会绞尽脑汁地制作产品说明书、功能演示视频等，目的就是想从不同角度更多、更有效的表达自己的商品的特性。对于普通商品而言，消费者Get程度低顶多是少用几个功能特性；但对于架构师生产的“产品”：架构设计成果而言，如果其消费者开发人员Get的程度低，那影响就会很严重，甚至可能会导致软件系统的开发彻底失败。

并且更不幸的是：我们的软件系统都是“复杂产品”。这样，如何表达和解读软件架构，弥合生产者与消费者之间的Gap，让开发者更多更深刻的理解软件架构这件“产品”便成为了架构师的困惑，日常架构设计工作中的难题，也是业界探索的重要课题。

架构设计是架构师与开发者之间的协议，只有有效的、充分的表达，协议才能被共识理解和忠实执行。业界在有效表达软件架构这条路上摸索了很多年，下面简单说说架构设计表达的演进历程。

2. 软件架构表达方式演进简史

软件架构表达的目的就是要直观地传达架构设计人员的思想和意图，使开发团队可以达成对架构设计的一致理解，促进各个团队协作，并作为开发人员编写代码以及管理人员推进项目的重要指导与参考。

2.1 自然语言描述

在软件工程的早期阶段，软件架构设计通常使用自然语言（如英语）进行描述。架构师会使用文档、规范和书面记录来表达架构设计的概念、原则、结构、组件和交互。然而，自然语言描述存在歧义性、解释性不足、理解起来较慢的问题，可能导致误解和沟通障碍。

2.2 图形化表达

人类大脑中传输的信息90%是视觉信息，其处理图形的速度要比处理文字的速度快上万倍。于是随着软件架构的复杂性增加，人们开始采用更直观、更易理解的图形化方法来描述架构设计(并辅以自然语言的文字描述)。

提到图形化表达，最简单的方法就是使用一支笔+一张白纸，基于自己“创造”的符号绘制草图(Sketch，以下草图来自c4model.com)：

这种非规范的框线草图虽然提供了灵活性，但付出的代价却是一致性，因为大家都在创造自己的制图符号，而不是使用统一的标准。

2.3 结构化的图形表达

结构化图是在设计表达迈向标准化方面走出的重要一步。结构化图包括数据流图、控制流图、层次图、组件图等，用于可视化表示系统的组件、模块、依赖关系和交互流程等(下图中元素来自维基百科)。

作为一种可以直观可视化描述与沟通架构设计的方式，结构化图形成为了表达架构设计的常见方法之一。不过，早期结构化表达的类型有限，无法涵盖所有环节，有的也没有形成标准，为了提高标准化程度，满足架构设计表达的全部需求，人们在二十世纪末推出了大一统的图形化建模语言UML。

2.4 统一建模语言(UML)

统一建模语言（Unified Modeling Language，UML）是一种通用的标准化、图形化建模语言，广泛用于软件架构和设计的表示，在软件架构表达方法方面具有里程碑意义：

UML第一次在规范层面对图形表示进行了标准化，它提供了一组规范化的图形符号，用于描述系统的结构、行为和交互。在那个Rational统一过程（RUP）以及面向对象设计方法如日中天的时代，人们每每进行设计时，言必称使用UML。UML在图形化、标准化表达设计图方面走到了至今为止都无人企及的高峰。

但是，20多年后的今天，UML并没有成为当时标准出品方期望的那个样子，没能成为表达软件系统设计的主流符号系统。也许是它的复杂性阻碍了有效沟通，让人们看到它的spec后就“望而却步”了。不过UML并没有死掉，它依然活着，UML规范中的一些图(Diagram)依然被大家常用，比如：序列图(Sequence Diagram)、用例图(Use Case Diagram)、类图(Class Diagram)等。

2.5 形式化表达

业界在寻求图形化表达标准化的同时，也有一个分支在寻求用自然语言的“标准化”表达方法，这就是软件架构设计的形式化表达，在这个领域形成的语言被称为架构描述语言(ADL)。ADL提供了一组特定的语法和语义规则，用于定义系统的组件、接口、依赖关系、行为和性能特征。ADL使架构师能够使用精确的语言来表达和分析架构设计，支持自动化的验证和分析工具，在学术研究这个小众领域还是很有受众的。不过，显然在大多数工程化淋雨，形式化表达门槛太高，对于软件架构在团队内快速有效建立共识起不到什么作用。

下面是一些ADL的实现，感兴趣的童鞋可以了解一下：

• xArch/xADL
• ACME
• AADL

2.6 多视角的表达

有了UML这个前车之鉴后，人们似乎也放弃了在图记号“标准化”之路上的继续探索了，而是回归问题本源：怎么有效，就怎么来。

在工程实践中，人们认清了一个事实：很难在一张大图(Diagram)中进行软件架构设计的有效表达。于是大家开始采用“盲人摸象”的策略，将一个架构按不同视角表达为不同的图(Diagram)，这样当开发人员将多个视角形成的图都理解后，也就理解了整个架构设计。

按照这个多视角表达的思路(也被称为是一种软件架构建模思路)，业界先后出现了：

• Kruchten 4+1 views

逻辑视图（Logical View）关注系统的功能和功能模块，描述系统中各个模块之间的关系、接口和行为。它展示了系统的静态结构和动态行为，以及模块之间的通信和信息流。

进程视图（Process View）描述系统的并发和分布式特性，关注系统中的进程、线程、任务以及它们之间的关系和通信。该视图展示了系统的并发性、性能、可伸缩性等方面。

物理视图（Physical View）描述系统在硬件和软件环境中的部署和分布情况，包括物理设备、网络拓扑、软件组件的部署位置等。它关注系统的部署架构、可靠性、安全性等方面。

开发视图（Development View）关注系统的软件开发过程和组织结构，描述软件模块的组织、构建、测试和部署过程。它展示了软件开发团队的组织结构、开发工具、版本控制等方面。

场景视图（Scenario View）描述系统在特定使用情境下的行为和交互，以用户场景、用例或故事来说明系统的功能和行为。它帮助验证和验证系统架构的正确性和适应性。

• C4 model

C4模型是一种简洁、易于理解的软件架构建模方法，由Simon Brown提出。它通过四个层次的视图来描述软件系统的不同方面，包括语境视图(Context Diagram，这里借鉴了《程序员必读之软件架构》)一书中对Context的翻译)、容器视图(Container Diagram)、组件视图(Component Diagram)和代码视图(Code Diagram)，如下图所示：

语境视图是最高层级的视图，用于描述软件系统与外部实体之间的关系和交互。它展示了系统所处的环境和与外部实体（如用户、其他系统、第三方服务等）的关系，以及它们之间的交互方式。

容器视图关注系统内部的软件容器及其之间的关系和交互。容器可以是物理的、虚拟的或逻辑的，它们承载着系统中的组件或服务。容器可以是应用程序、数据库、消息队列、Web服务等。容器视图描述了系统的主要部件，以及它们之间的依赖关系和通信方式。

组件视图进一步展开容器视图中的组件，描述系统内部的组件及其之间的关系和交互。组件视图展示了系统的模块、类、库或其他可重用的软件单元，并显示它们之间的依赖关系、接口和通信方式。

代码视图是最底层的视图，关注具体的代码实现细节。它用于描述系统中的类、函数、方法等代码单元的结构、关系和实现细节。代码视图可以是面向对象的类图、模块图或其他代码组织结构的表示方式，用于帮助开发人员理解和浏览源代码。

下面示意图可以更直观的展示出语境、容器、组件以及代码之间这种逐渐“展开”的层次关系：

通过C4模型的这四个层次的视图，架构师可以逐渐深入地描述和表达软件系统的不同层次和组成部分，从整体到细节，帮助团队成员和利益相关者更好地理解和沟通软件架构。

• Arc42

Arc42是一种用于软件架构文档化的模板和方法，它提供了一套规范和指导原则来描述软件系统的架构。下面是Arc42的全景图：

我们看到：Arc42模板也包含了多个视图，每个视图都关注系统架构的不同方面，包括Context、Building Block View、Runtime View以及Deployment View等。

Context View：描述系统与其外部环境之间的关系和交互，强调边界的概念，分为技术Context与业务Context。

部署视图（Deployment View）描述了系统的部署架构和环境，包括物理设备、服务器、网络拓扑以及协议等信息。

构件视图（Building Block View）描述了系统内部的组件、模块、子系统、包等，并展示它们之间的关系和依赖。构件视图是源码结构的概览。

运行时视图（Runtime View）描述了系统在运行时的行为和交互以及具体场景下对其他构件的运行时依赖。使用序列图、状态图等方式可展示系统的运行时行为。

2.7 Diagrams As Code

架构设计不是一成不变的，需要不断演进，因此架构视图也需要“与时俱进”的更新。但直接更新图片格式似乎很不方便，也无法在形式上很好的达成一致，于是一些基于DSL语法生成架构设计图(Diagram)的工具便涌现了出来，比如：PlantUML、Structurizr、Mermaid等。有了这些工具，架构师便可以使用文本编辑器来“画图”，支持“所见即所得”。并且由于Diagrams As Code(代码即图)，我们可以将架构设计图与版本控制系统很好地集成。

到这里，我们知道了基于多视角+“Diagrams As Code”是目前的主流的架构设计表达和实践方法，那么我们在软件架构表达实践中，究竟选择哪几个视角来表达呢？这个目前没有统一标准。调研了4+1 Views、C4 model以及Arc42后，我这里说说自己日常做架构表达时使用的最小视图集。

3. 最小图集

很多读者可能听说或学习过或实践过金字塔写作，金字塔写作原理是一种用于新闻报道和科技写作的写作方法，它的核心思想是将最重要的信息放在文章的开头，然后逐渐向下展开，提供更多的细节和背景信息。

金字塔写作的优势在于：

• 它可以迅速吸引读者的注意力，让读者在最短时间内了解文章的核心内容；
• 它还可确保信息传递：将最重要的信息放在开头，可以避免读者在阅读过程中错过关键信息或迷失在细枝末节中，确保信息有效地传达给读者；
• 它还具备灵活性和可定制性，不要求严格按照一个固定的结构来组织文章，而是提供了一种基本的思路和原则，可以根据具体情况进行调整和定制，以适应不同的写作需求和读者群体。

我理解，金字塔写作方法之所以能够成功，其本质是站在了读者的角度去思考问题，想读者之所想，做读者之所需。

软件架构表达的目的也是让开发人员快速深入的理解架构，与设计人员达成共识，指导后续软件系统的实现。所以要想形成有效表达，我们就需要像金字塔写作那样站在开发人员的角度来考虑架构表达，借鉴金字塔原理，自上而下，先表达最重要的信息，然后逐渐向下展开，避免开发人员在理解过程中错过关键信息或迷失在细枝末节当中。

综合前面介绍的多种Views的方法，我们觉得软件架构表达的起点，即第一个图必须是语境图(Context Diagram)。

3.1 语境图(Context Diagram)

语境图表达的是系统最高的抽象层次，是最高视角，全局视角。通过语境图，可以解决开发人员在内心中提出的下面问题：

• 我们构建的（或已经构建的）软件系统是什么(What)？
• 谁会用它？
• 如何融入已有的IT环境？
• 系统的边界是什么？（业务的，技术的)

语境图不会也不应该展示太多细节，它是软件系统设计图的起点。后续的图都是用“放大镜”将我们的系统放大后的细节的表达。当牵涉到理解系统间接口的问题时，语境图还可以为你识别可能需要沟通的人提供了一个起点。

语境图向开发者展现的重点在于软件系统的范围以及与外部的交互行为（用户< – >系统、系统< – >系统等等）。下面是使用structurizr绘制的一个语境图的实例：

语境图中心蓝色的矩形框代表的是我们的软件系统，上方的user、role、actor是我们的软件系统的用户；client是与我们的软件系统交互的系统，是系统到系统交互的一个代表；在我们的软件系统、Inner System1和Inner System2之外有一个虚线框，代表了企业范围；而Inner System1和Inner System2是我们的软件系统在企业内部依赖的系统；同时，我们的软件系统还依赖企业外部的Outer System1和Outer System2。

上述语境图对应的structurizr dsl代码如下：

// system context diagrams

workspace {

    model {
        u = person "User"
        r = person "Role"
        a = person "Actor"
        c = softwareSystem "Client Software System" {
            tags "client"
        }

        enterprise = group "Enterprise A" {
            s = softwareSystem "Our Software System" {
                tags "server"
            }

            d1 = softwareSystem "Inner System1" {
                tags "dep"
            }

            d2 = softwareSystem "Inner System2" {
                tags "dep"
            }
        }
        d3 = softwareSystem "Outer System1" {
            tags "dep"
        }

        d4 = softwareSystem "Outer System2" {
            tags "dep"
        }

        u -> s "Uses"
        r -> s "Uses"
        a -> s "Uses"
        c -> s "Call"
        s -> d1 "Uses"
        s -> d2 "Uses"
        s -> d3 "Uses"
        s -> d4 "Uses"
    }

    views {
        systemContext s {
            include *
            autoLayout
        }

        styles {
            element "server" {
                background #1168bd
                color #ffffff
            }

            element "dep" {
                background #e5e4e2
                color #000000
            }

            element "client" {
                background #e5e4e2
                color #000000
            }

            element "Person" {
                shape person
                background #08427b
                color #ffffff
            }
        }

    }

}

基于语境图，就好比我们站在万米高空一览Our Software System。不过对于架构设计表达来说，这还不够，现在是时候下降高度让视野进入到系统内部去挖掘一些细节了。

3.2 容器图(Container Diagram)

在从万米高空的系统全局视角了解了我们的软件系统是什么后，我们将第一次进入到系统内部。我们现在所处的高度是100米，在这个高度上，可以清晰地看到软件系统的整体形态、内部脉络、技术选择、职责分布以及各个部分之间是如何交流的。我们将每个部分称为一个容器(container)。一个容器通常可以表示一个应用/服务或数据存储，如果你的软件系统采用了微服务架构，那么将每个服务作为一个容器通常是可行的。

针对每个容器，我们可以设置它的属性：名字(如Web App、API网关、关系数据库存储、订阅服务等）、实现技术(如mvc等)以及功能性的描述。在容器间的联系上我们可以附加上通信方式(json over http、gRPC、websocket等)。

下面是上面语境图中的My Software System的容器图：

在这个容器图中，我们看到了系统支持通过Web app和mobile app访问和使用；系统的入口使用了API网关；系统内部分为业务服务和基础服务，基础服务封装了到关系数据库、对象存储(oss)的接口(关系数据库和oss都是技术选择)；业务服务可以调用企业内部服务，亦可调用企业外部服务，并且明确了调用方式。

下面是生成上述容器图的structurizr的代码：

// container diagrams

workspace {

    model {
        u = person "User"

        enterprise = group "Enterprise A" {
            s = softwareSystem "Our Software System" {
                tags "server"

                mobileApp = container "Mobile App" {
                    tags "container"
                }

                webApp = container "Web App" {
                     tags "container"
                }

                apiGw = container "API Gateway" {
                     tags "container"
                }

                biz1 = container "Business Service 1" {
                     tags "container"
                }

                biz2 = container "Business Service 2" {
                     tags "container"
                }

                biz3 = container "Business Service 3" {
                     tags "container"
                }

                base1 = container "Base Service 1" {
                     tags "container"
                }

                base2 = container "Base Service 2" {
                     tags "container"
                }

                base3 = container "Base Service 3" {
                     tags "container"
                }

                rds = container "Relational Database system" {
                     tags "container"
                }

                oss = container "Object Storage Service" {
                     tags "container"
                }
            }

            d1 = softwareSystem "Inner System1" {
                tags "dep"
            }

            d2 = softwareSystem "Inner System2" {
                tags "dep"
            }
        }

        d3 = softwareSystem "Outer System1" {
            tags "dep"
        }

        d4 = softwareSystem "Outer System2" {
            tags "dep"
        }

        u -> mobileApp "Uses"
        u -> webApp "Uses"
        mobileApp -> apiGw "Makes API calls to" "JSON/HTTPS"
        WEBApp -> apiGw "Makes API calls to" "JSON/HTTPS"
        apiGw -> biz1 "Route API calls to" "gRPC"
        apiGw -> biz2 "Route API calls to" "gRPC"
        apiGw -> biz3 "Route API calls to" "gRPC"
        biz1 -> base1 "Inner API calls to" "gRPC"
        biz1 -> base2 "Inner API calls to" "gRPC"
        biz2 -> base2 "Inner API calls to" "gRPC"
        biz2 -> base3 "Inner API calls to" "gRPC"
        biz3 -> base3 "Inner API calls to" "gRPC"
        base1 -> rds "Reads from and writes to" "Raw SQL"
        base1 -> oss "Reads from and writes to" "HTTPS"
        base2 -> rds "Reads from and writes to" "Raw SQL"
        base3 -> oss "Reads from and writes to" "HTTPS"
        biz1 -> d1 "Make API calls to" "HTTP"
        biz2 -> d3 "Make API calls to" "HTTP"
        biz3 -> d2 "Make API calls to" "HTTP"
        biz3 -> d4 "Make API calls to" "HTTP"
    }

    views {
        container s {
            include *
            autoLayout
        }

        styles {
            element "server" {
                background #1168bd
                color #ffffff
            }

            element "container" {
                background #1168bd
                color #ffffff
            }

            element "dep" {
                background #e5e4e2
                color #000000
            }

            element "Person" {
                shape person
                background #08427b
                color #ffffff
            }
        }

    }

}

注：在容器图这个层次上，group关键字没有起作用，导致企业内部服务与外部服务放在一起了。

按照C4 model的思路，接下来我们会再下降高度，来到10米的高空，进入到某个容器的内部。但容器内部的设计在我看来属于详细设计范畴，如果采用的是微服务架构，那么容器内部的设计就相当于某个服务的设计。所以这里，我并未将这部分作为架构表达的必需之图。

3.3 序列图(Sequence Diagram)

无论是语境图，还是容器图，从大类来看，都属于静态的结构图。但做过软件系统设计和研发的童鞋都知道，仅有静态的表达还是不够的，不足以传达软件系统的所有信息，我们还需要对动态行为的表达。这就是为什么我将序列图作为软件表达最小图集一份子的原因。

可能有些人将序列图作为需求分析阶段的产物，其实，序列图既可以在需求阶段产生，也可以在架构设计阶段产生。它在不同阶段有不同的应用和目的。

在需求阶段，序列图被用于描述系统的功能需求和行为。它可以帮助分析和定义系统的用例或用户故事，以及系统与外部实体（如用户、其他系统、服务等）之间的交互过程。通过序列图，需求分析人员和开发团队可以更清晰地理解系统的功能需求，并就用户与系统之间的交互进行沟通和确认。

在架构设计阶段，序列图被用于描述系统的结构和组件之间的交互。在这个阶段，序列图通常用于展示系统的运行时行为、组件之间的消息传递和调用关系。架构师使用序列图来验证系统的设计方案，确保系统的各个组件按预期互相协作，并满足功能和性能要求。

这里的序列图，可以对应前面的Arc42的Runtime View，以及C4 model的Dynamic Diagram。

序列图也是UML语言中最常被使用的一种Diagram，即便是在UML不那么被提及的今天，我个人也推荐使用UML的序列图来表达，而不推荐用structurizr来画了，structurizr在序列图方面的表达能力还是弱了许多。

你可以用你最喜欢的画图工具来绘制UML序列图（比如我经常用的drawio），也可以选择plantuml这种基于DSL语法生成序列图的方式来绘制。plantuml对序列图的支持还是非常好的，支持了序列图的大多数元素，可以绘制出非常复杂的图来(下图来自plantuml官网)：

针对一个复杂的软件系统，我们可能需要针对不同的Container(或更进一步的组件)绘制较多的序列图，至少要覆盖到软件系统各个Container的核心交互流程。

3.4 部署图(Deployment Diagram)

无论是C4模型，还是arc42，亦或是UML语言，都包含部署图。在软件架构表达时，准确表达部署设计，对开发人员后续的实现具有很好的指导作用。通过部署图，架构设计人员可以说明静态图中的软件系统和/或容器实例是如何部署到给定部署环境（如生产、暂存、开发等）中的基础设施上的，比如下面这个部署示意图(来自c4model.com)：

我们看到部署图中的核心角色是部署节点(Node)，它代表了软件系统/容器实例运行的位置；可能是物理基础设施（如物理服务器或设备）、虚拟化基础设施（如IaaS、PaaS、虚拟机）、容器化基础设施（如Docker容器）、执行环境（如数据库服务器、Java EE Web/应用服务器、Microsoft IIS）等，并且部署节点还可以嵌套。此外，右下角的”x N”表示需要多少个部署节点。

通过部署图还可以表达云基础架构的情况(下图来自c4model.com)，可以包含DNS、负载均衡器以及防火墙等部署的基础设施的节点：

structurizr对于部署图支持的还不错，还可以像上图那样使用不同公有云提供商特色的Theme来绘制部署图。

到这里，我们已经“凑齐”了表达软件系统架构的最小图集：语境图、容器图、序列图和部署图。我们要学会灵活使用这些图。在软件系统十分复杂的情况下，我们可以将语境图分为System Landscape diagram和多个sub system的语境图，之后以此类推，对于每个sub system做容器图等。

4. 最小图集之外的图(可选)

有些公司或组织会将架构设计阶段延伸到container内部，这样对软件系统架构的表达就要延伸到详细设计，甚至是编码阶段时，我们就要考虑下面两个类型的Diagram了：组件图和代码图。

4.1 组件图(Component Diagram)

如果容器图阶段，你所在的高度是100米，那么组件图阶段，你将位于高度为10米的空中，这足以让你看清容器中每个组件(Component)的细节。

组件图就是容器内部的设计，它涉及到容器内部各个逻辑组件的结构与组件间的交互。在这个层次，你可以使用你擅长的面向对象设计方法，或者面向契约/接口的设计模式，你也可以使用一些成熟的企业应用设计模式，比如MVC等。

下面是一张组件图示例(来自c4model.com)：

我们看到中间的部分就是API Application这个容器内部的逻辑组件结构与交互情况。有些时候在组件图这一层面，我们甚至可以对照初对应项目中的代码布局结构。

对于组件图中关键组件间的复杂交互流程，可辅以序列图的方式来表达。

此外，组件图可以使用structurizr绘制，语法和语境图、容器图十分相似。

4.2 代码图(Code Diagram)

再下降，我们来到离地面1米的高度，我们几乎要躬身入局，参与编码了。通常架构设计不会到达这个阶段，架构师们在100米或10米高度完成任务后，就可以去休息了。

但如果包含这个阶段，我们要给出的便是代码图(Code Diagram)，再直白些，就是UML类图、E-R关系图等，下面是一个示意图：

这是一个直面开发人员的图，你可以看到编程语言中的那些机制：接口、继承、实现等等，开发人员甚至可以通过工具将这样的uml class图直接转换为项目的骨架代码。

4. 小结

本文首先介绍了为什么软件架构需要有效表达，以便开发者更好地理解架构设计。然后回顾了软件架构表达方式的演进历史，从自然语言描述到图形化表达，再到结构化图形表达、UML、形式化表达，最终发展到现在的多视角表达方式。

文章结合笔者实践经验，借鉴多个多视角软件架构模型，提出了最小图集的概念，笔者认为有效表达软件架构最关键的视角有四个，分别是:

1. 语境图：描述系统的整体位置和边界
2. 容器图：展示系统内部的容器及其关系
3. 序列图：呈现容器内组件以及组件之间的交互行为
4. 部署图：阐明系统在实际环境中的部署情况

此外，我认为还可根据需要补充组件图和代码图等更细节的视图。这套最小图集能较全面地表达软件系统的静态结构和动态行为，帮助开发者理解架构设计。

总的来说，该文章从工程实践的视角出发，提出了一套行之有效的软件架构表达方法，对于架构设计的团队沟通及实现具有很好的指导意义。

btw，在容器图或组件图设计阶段，如果要完善工程设计，还可以结合具体的接口文档予以表达，比如基于Swagger的API设计文档等。

5. 参考资料

• 《Software Architecture for Developers》- https://book.douban.com/subject/26248182/
• The C4 model for visualising software architecture – https://c4model.com
• Unified Modeling Language Specification – https://www.omg.org/spec/UML
• The Unified Modeling Language – https://www.uml-diagrams.org
• Communicating Software Architecture – https://arquisoft.github.io/slides/course2021/EN.ASW.TE03_Documentation.pdf
• arc42 – https://arc42.org

“Gopher部落”知识星球旨在打造一个精品Go学习和进阶社群！高品质首发Go技术文章，“三天”首发阅读权，每年两期Go语言发展现状分析，每天提前1小时阅读到新鲜的Gopher日报，网课、技术专栏、图书内容前瞻，六小时内必答保证等满足你关于Go语言生态的所有需求！2023年，Gopher部落将进一步聚焦于如何编写雅、地道、可读、可测试的Go代码，关注代码质量并深入理解Go核心技术，并继续加强与星友的互动。欢迎大家加入！

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：

• 微博(暂不可用)：https://weibo.com/bigwhite20xx
• 微博2：https://weibo.com/u/6484441286
• 博客：tonybai.com
• github: https://github.com/bigwhite
• Gopher Daily归档 – https://github.com/bigwhite/gopherdaily

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。