多年来，我一直在使用Miro来记录软件并和我的团队协作。它是一个绝佳的工具，是现代的数字白板。不过话说回来，我很少在最初的创意会议后再次查看白板。这可能既是产品的优点也是缺点。它非常适合团队协作和分享想法。为什么它不成为我回顾文档的地方呢？
我认为问题在于变更管理。过时的文档就变得毫无用处，随着软件不断地发展，又有谁会回头去更新一个Miro看板呢？即使他们真的去更新了，你又怎么知道哪些地方被修改了呢？
我脑中直接的答案是找出如何将这些图表转化为代码。在研究潜在解决方案时，我考虑了三个标准。
- 可读且快速： 如果编写文档耗时太多，那么文档将不会被使用。作者只需简单描述图表，不必担心排版或美观。
- 专业展示： 我希望可以将这些图表不仅分享给团队，还能分享给其他相关方（包括管理层和投资者）。
- 集成： 我们团队大多数人都在使用 VSCode，并且所有人都使用 GitHub，因此必须无缝衔接。
为了测试这些解决方案的可行性，我创建了一个简单的AWS架构图，记录了一个基于微服务架构的博客应用。当然，现实中我们不会这么设计一个博客，但我希望确保解决方案能应对几个服务带来的适度复杂性。
我找到了两个符合这三个标准的选项：Python 包 “Diagrams as Code” 和一个 Javascript 选项 “Mermaid”。Mermaid 似乎是几个渲染库的混合体，而 Diagrams as Code 较新。Diagrams as Code 使用了成熟的 GraphViz 项目，而 Mermaid 支持更多种类的图表。我们测试的重点是架构图，公平地说，Mermaid 将其视为 beta 版，而 Diagrams as Code 则专注于此。
这两个项目的当前维护状态也值得关注。Mermaid 正在崛起。作者最近还投资并启动了一个新业务“Mermaid Charts”，这似乎是为了与 Miro 这样的工具一争高下。这可能是个好现象，意味着该产品将有长期支持，但也可能是个问题，如果他们更改了许可协议。我已经看到他们对开源项目关注减少，仅开发付费功能。
与此同时，Diagram as Code似乎被搁置了一段时间，但维护者最近几个月开始变得活跃起来，并且拉取请求开始被处理。鉴于存在的问题和拉取请求的数量（在我看来，这比星标更有参考价值）。
在没有更多投入时间的情况下，我对代码库无法做出强有力的评价。两者都奠定了坚实的基础，并且设计得相当不错。因为不得不修复一些错误来完成实际图表，我对Mermaid更加熟悉。作为代码的图表几乎可以100%直接使用，唯一的问题是，图表的右侧线条被截断。因为时间不够，我只好用GIMP把问题解决了。
我觉得 Mermaid 已经到了需要重构的地步了。它涵盖了更多的图表类型，因此每种图表类型几乎都有自己的代码库，几乎没有代码共享。这一点在尝试使用主题功能时尤为明显。软件可以从一个通用的配置文件和渲染模块中大大受益。我担心他们不会优先考虑这类提高用户体验的改进，因为他们正努力鼓励客户使用高级平台。
为了展示这些工具的实际效果，我为一个假设的（但显然过于复杂）博客应用程序创建了一个 AWS 架构图。你会发现 Mermaid 使用它自己的标记语法（可以在 GitHub 上嵌入 Markdown 代码！），而 Diagrams as Code 则利用了 Python 中的操作符重载功能。两者都提供了一个不错的编辑体验。
下面展示Mermaid的图表和它的输出结果。
架构-Beta
服务 dns(图标:aws-route53)[Route 53]
服务 cf(图标:aws-cloudfront)[CloudFront]
服务 lb(图标:aws-ec2)[负载均衡]
服务 ui(图标:nextjs)[UI]
服务 gateway(图标:aws-api-gateway)[API Gateway]
服务 auth(图标:aws-lambda)[认证]
服务 authDb(图标:aws-dynamodb)[Auth DB]
auth:R --> L:authDb
服务 blog(图标:aws-lambda)[博客]
服务 blogDb(图标:aws-dynamodb)[Blog DB]
blog:R --> L:blogDb
服务 analytics(图标:aws-lambda)[分析]
服务 analyticsIndex(图标:aws-open-search)[OpenSearch]
analytics:R --> L:analyticsIndex
dns:R --> L:cf
cf:R --> L:lb
lb:B --> T:ui
cf:R --> L:gateway
gateway:R --> L:auth
gateway:R --> L:blog
gateway:R --> L:analytics由 Mermaid 生成的图
你可以马上就能看出我确实考虑了图表的实际布局。这确实是一个让图表看起来整洁的重要因素，我本可以通过手动添加一个连接点并更好地排列这三个服务，让图表看起来更完美。但这不是在某种程度上违背了这个工具的初衷吗？我只想专注于材料，让工具为我自动生成图表。这可能有点要求过高，但我怀疑这并不会太远了，所以我担心投资于这样一种视觉描述性很强的标记语言。
这里有一个使用Diagrams as Code生成的相同图示：
从 diagrams 导入 Diagram
从 diagrams.aws.network 导入 APIGateway, ALB, Route53, CloudFront
从 diagrams.programming.framework 导入 NextJs
从 diagrams.aws.compute 导入 Lambda
从 diagrams.aws.database 导入 Dynamodb
从 diagrams.aws.analytics 导入 AmazonOpensearchService
with Diagram(None, show=False, graph_attr={"pad": "1"}),:
gw = APIGateway("API网关")
lb = ALB("负载均衡器")
cf = CloudFront("云前端")
Route53("DNS") >> cf
cf >> lb
cf >> gw
lb >> NextJs("用户界面")
gw >> Lambda("身份验证服务") >> Dynamodb("身份验证数据库")
gw >> Lambda("博客服务") >> Dynamodb("博客数据库")
gw >> Lambda("分析服务") >> AmazonOpensearchService("OpenSearch") # OpenSearch通过 Diagrams as Code 生成的图
感谢巧妙的运算符重载，语法几乎没有什么不同。这种情况下，即使你不太熟悉 Python，用 Diagrams as Code 编写或阅读图表也一样轻松，不过，你需要一个环境来渲染这些图。Mermaid 在这方面略胜一筹，尤其是在 VSCode 插件和 GitHub 的内置渲染方面（不过也有一些需要注意的地方）。
所以我会用什么呢？说实话，我也不确定。老实说，我对“图解即代码”这个概念一开始很有信心。除了我之前提到的例子，它在处理复杂架构图时表现得更佳。不过，它的适用范围非常有限。Mermaid在处理实体关系图时表现得更好，我可能会在后面的文章里探讨这方面的内容。不过，我不太喜欢Mermaid将布局直接写入架构图语法的做法，不过，它的其他图表类型却没有这个问题。我希望他们在正式定版前能改变这种做法。
说到底，我将密切关注这两个项目。看看会怎么样会更自然。图表即代码的维护者是否会认为在现有良好基础上继续发展是值得的，以及 Mermaid 是否会专注于开源项目的发展和重构，还是仅仅专注于 SaaS 平台。虽然这是一个小众领域，但我认为，正确的产品有可能成为下一个 Terraform 这样的视觉文档工具。
有没有错过这两个产品的一个很好的替代选择？请告诉我。