如果你曾经访问过 GitHub 上的一个项目（例如），想要了解它如何融入更大的系统，你一定会认同，当你在初始登录页面上（或很容易从那里找到）找到一两个图表时，会感到如释重负。 这篇文章是关于架构的重要性，特别是图表的重要性。
我强烈支持开源，但是源代码不足以使一个项目成功，甚至可以说，不足以成为一个 *真正* 的开源项目：你的文档不仅应该对所有人可用，而且应该对所有人 *易于访问* 。 如果你想让人们参与进来，提供一个入口至关重要。
除此之外，我认为我们对开源的多样性负有责任（和机会！）。 提供图表有助于解决（至少！）四种类型的多样性
- 母语不是你的主要文档所用语言的人
- 阅读大量文本有困难的人（例如，有阅读障碍的人）
- 更喜欢视觉而非文字思考的人（像我一样！）
- 想从不同角度（例如，安全性、管理、法律）理解你的项目的人
这篇文章的由来是我最近参加了一个虚拟演示。 演示没有成功，但我们都没有感到压力：这是一个内部演示，而且这种情况经常发生。 我们都熟悉这种情况，当项目团队负责人（正在展示幻灯片）放映几张幻灯片后，她的屏幕上弹出一个来自团队成员的消息，内容是“演示不行！”时，我们都为她感到惋惜。
在道歉之后，她问我们是想完全放弃还是只是讨论他们手头的信息。 我们选择了后者——毕竟，大多数不突出用户体验组件的演示，除了终端窗口之外，展示不了多少东西，至少我们中的大多数人可以在半小时左右的时间里伪造出来。
幸运的是，演示团队的成员有很多关于演示原本会展示的内容的信息，并且有一个特别好的架构图可供讨论，所以尽管演示出了问题，我们还是进行了一次富有成效的会议。 她回答了几个问题，然后我提出了一个关于安全性的问题。
这篇文章本来可以写一个早期演示中出现的安全漏洞：另一个安全性被遗留到后期（通常为时已晚）的例子，到那时集成起来既困难又昂贵。 然而，很明显，该团队已经考虑了安全性的具体方面，包括网络上的安全性（传输中）和存储中的安全性（静态）。 虽然可能还有改进的空间（什么时候没有呢？），但一位团队成员在通话期间通过消息发送给我更多文档，让我能够理解团队所做的一些选择。
这篇文章 *实际* 要讲的是我们能够进行讨论。 幻灯片中包含了一个架构图，显示了所有主要组件，并用箭头显示了数据流的方向。 它清晰明了，并用颜色编码来显示不同组件的来源——哪些组件来自外部项目，哪些组件来自内部项目，以及哪些组件是这次演示的新组件。 参与通话的人——都是技术人员——能够一目了然地了解情况，而提供描述的团队负责人对各种流程也有清晰的解释。 她的团队成员也加入了进来，回答具体问题或提供关于特定要点的更多细节。 这应该是技术讨论的方式，尤其让我高兴的一件事是（除了该项目已经考虑过安全性之外！）：有一个架构图可以讨论。
世界上没有足够的安全专家，这意味着并非每个项目都有机会让安全社区的成员仔细审查其设计的每个阶段。 但当需要分享时，一张图表是无价的。 我不敢想象有多少次我被要求查看一个项目，就其安全性方面提出我的看法，但发现所有可用的只是一堆代码和组件文档，没有解释它们是如何组合在一起的，更糟糕的是，没有架构图。
当你构建一个项目时，你和你的团队通常都专注于细节，以至于你 *知道* 所有组件是如何组合在一起的，并且可以将它们记在脑海中，或者向同事描述关键点。 问题在于，当有人需要提出不同类型的问题或从不同的角度审查架构和设计时。 一张图片——一个架构图——是向外部人员（或项目的新成员）介绍技术层面正在发生的事情的好方法。 它还具有许多额外的优点
- 它迫使你思考是否所有内容 *都可以* 用这种方式来描述。
- 它迫使你考虑抽象级别以及应该在什么级别显示什么内容。
- 它可以揭示以前不清楚的关于依赖关系的假设。
- 它有助于显示各个组件之间的数据流。
- 它可以让你与母语不是你的主要文档所用语言的人进行更简单的对话。
需要明确的是，这不仅仅是一个安全问题——高可用性、数据一致性、性能或弹性等其他非功能性需求也是如此——但我是一个安全人员，这就是我体验这个问题的方式。 我也意识到我有一个非常视觉化的头脑，这就是我喜欢掌握新事物的方式。 但即使对于那些不倾向于视觉的人来说，一张图表至少提供了一个机会来确定自己的方向，并弄清楚你需要深入研究代码或执行的哪个地方。 我也相信，对于任何具有重大复杂性的系统，如果没有架构图，任何人都不可能考虑所有的安全含义（或任何更高阶的涌现特性和质量）。 这也包括设计系统的人，因为没有系统是独立存在的（或者说没有意义），所以你不可能长时间地将 *所有* 这些部分都记在脑海中。
我之前写过关于 *构建演化架构* 这本书，它在帮助项目思考如何管理可能变形或改变优先级的需求方面做得很好。 毫不奇怪，这本书大量使用了架构图。 Enarx，一个我 密切参与 的项目，一直有很多图表，所以我知道这里涉及一些开销，包括在设计更改时更新图表，以及考虑为文档的不同使用者提供哪些抽象，但我真的相信这是值得的。 每当我们向新成员介绍该项目或进行演示时，我们都会确保至少包含一张图表（通常更多），当我们在演示结束时收到问题时，它们几乎总是以诸如“请回到幻灯片 *x* 上的图表”之类的短语开头。
我敦促你创建图表，既为了你自己的利益，也为了将来会查看你的项目的任何人。 这是成为一个开放项目的关键部分——架构的开放意味着代码，以及因此项目本身，变得更容易访问，也对更广泛的社区更加开放。 社区成员会感激这一点（你也应该如此）。 你的图表不需要是完美的。 但它们确实需要在那里。
9 条评论