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