自动生成代码运行时行为的序列图

2025-05-24

自动生成代码运行时行为的序列图

序列图常被誉为“UML 中最精彩的部分”。其固有结构——对象在页面上流动，时间在页面上向下流动——直观易学。对于开发人员和非技术开发人员（例如工程经理和产品经理）来说，序列图是讨论代码设计时最实用的工具之一。

更新！2023 年 4 月我们现已开发此功能的新版本，该版本完全交互式，无需 Java 或 PlantUML。了解更多关于JetBrains AppMap 交互式序列图的信息。

或者，继续阅读，了解我们如何使用 AppMap 和 PlantUML 👇 👇 👇 首次开发此功能

过去，创建序列图需要专门的软件。但随着“一切皆代码”运动的兴起，PlantUML和Mermaid等工具提供了一种相当基础的文本语言来生成序列图，从而保持了序列图的实用性。不妨想想：用 Markdown 来制作图表。

虽然使用文本文件创建序列图相当容易（而且很有价值！），但仍然需要付出努力。而且，作为文档，图即代码仍然受到文档的致命弱点——过时。

如果您可以毫不费力地同时获得序列图和序列图，那会怎样？继续阅读，了解如何仅通过运行代码即可生成序列图。

注意：比起阅读，你更喜欢观看吗？在 YouTube 上观看“使用 VSCode 自动生成 Rails 应用的序列图”

视频缩略图

工作原理

序列图展示了特定的代码流程，例如 HTTP 请求或作业处理。因此，生成序列图的第一步是按照特定的流程运行代码。我建议两种方法来实现：

  1. 运行测试用例
  2. 运行您的应用程序并与其交互，可以通过其 UI 或通过从Postman等工具发送 API 请求。

为了生成代码行为图，我们需要准确记录代码运行时发生的情况。为此，我们将使用 AppMap，这是我创建的一款免费开源的运行时代码分析工具。您可以将 AppMap 与 Ruby、Python、Java 和 JavaScript 结合使用 - 您可以在此处找到 AppMap 的设置说明。AppMap 可以记录测试用例和实时应用程序 API 请求，因此您可以使用其中任何一种技术来获取图表数据。

录制测试用例或交互式会话后，您可以使用 AppMap CLI 或 VSCode 的 AppMap 扩展来生成序列图。我将在这里介绍这两个选项。

在这两种情况下，AppMap 工具都会生成一个 PlantUML 文件，然后将其渲染为 SVG。因此，在继续操作之前，请下载 PlantUML JAR 文件；撰写本文时的最新版本是plantuml-1.2022.13.jar。本文的其余部分将假设您已将此文件保存为~/Downloads/plantuml.jar。请根据需要进行调整。

注意您还需要有java可用的。在 MacOS 上，您只需运行 即可brew install java。

注意：您可以在此 Gist 中找到此博客文章中使用的所有文件的副本

VSCode 扩展

首先，使用 VSCode 扩展 - 因为它更简单一些。

首先从 VSCode Marketplace 安装AppMap 扩展。如果您尚未配置项目，系统会提示您配置 AppMap。项目设置完成后，请将 AppMap 配置更改提交到 Git，以便团队其他成员无需自行完成设置过程即可使用 AppMap。

现在，打开 VSCode 设置：

打开 VSCode 设置

然后搜索“AppMap Sequence Diagram”并配置PlantUML JAR的位置。

配置PlantUML JAR 位置

您已准备好生成序列图！点击扩展侧边栏中的图标打开 AppMap 视图，然后右键单击 AppMap 以打开上下文菜单。选择“AppMap 视图：生成序列图”。

AppMap 序列图上下文菜单

现在您将看到两次提示。第一次，只需按Enter 键接受默认设置。看到生成的图表后，您可以使用这些选项自定义其行为。

您将看到一个简短的进度指示器，然后您的图表将在浏览器中打开！

解释图表

这是我从Rails 示例应用程序第六版生成的序列图。（你喜欢冒险吗？试试生成 Mastodon 的 AppMaps 吧！）。

示例序列图

从左到右，您可以看到入站 HTTP 服务器请求POST /login。从那里，代码流向包controllers，然后通过helpers、models到数据库，再通过views。

每个从左到右的箭头代表一个 HTTP 服务器请求、函数调用、SQL 查询或 HTTP 客户端请求。从右到左的箭头代表返回值。

当代码循环运行时，您会看到一个Loop包含重复行为的框。

这是一个循环的示例，同样来自 Rails 示例应用程序，其中两个 SQL 查询序列重复了 29 次！这是一个常见的性能缺陷，称为 N+1 查询 - 这里有一篇关于 Rails 中 N+1 查询的博客文章。

序列图循环示例

N+1 查询可能很难发现，因为所有这些查询都是由 ORM 系统（例如 ActiveRecord (Rails)、Hibernate (Java) 或 Django ORM (Python)）自动发出的。在序列图中，它们非常明显！（您也可以使用 AppMap自动识别类似这样的性能缺陷。）

导出和共享

如果您想查看生成的 PlantUML 代码，请点击 AppMap 将其打开，然后转到 Explorer 视图。在 appmap.json 文件旁边，您将看到 PlantUML 文件 ( .uml) 和 SVG 文件 ( .svg)。

PlantUML 和 SVG 代码

您可以将此 UML 文件或 SVG 放入任何其他工具中，例如 GitHub Issue、Jira 票证、拉取请求或 Slack 消息。

命令行界面

您还可以使用 AppMap CLI 生成序列图。AppMap CLI 是一个名为 的 NPM 包@appland/appmap，因此有三种方法可以调用它：

  • 使用 npm 安装（npm install --save-dev @appland/appmap; npm run appmap）
  • 使用 yarn 安装（yarn add --dev @appland/appmap; yarn run appmap）
  • npx @appland/appmap@latest使用 npx( )运行它

我将使用选项 (3)，因为它易于记录。但为了避免反复从 NPM 下载软件包，你可能需要使用 (1) 或 (2)。

首先我们来看一下命令帮助。

$ npx @appland/appmap@latest sequence-diagram --help
appmap sequence-diagram appmap

Generate a sequence diagram for an AppMap

Positionals:
  appmap                                                     [string] [required]

Options:
      --version     Show version number                                [boolean]
  -v, --verbose     Run with verbose logging                           [boolean]
      --help        Show help                                          [boolean]
  -d, --directory   program working directory                           [string]
      --output-dir  directory in which to save the sequence diagrams
      --format      output format
                             [choices: "plantuml", "json"] [default: "plantuml"]
      --exclude     code objects to exclude from the diagram
Enter fullscreen mode Exit fullscreen mode

对于基本用法，你真正需要的唯一选项就是appmap参数。以下是一个例子：

$ npx @appland/appmap sequence-diagram tmp/appmap/minitest/Following_followers_page.appmap.json
Printed diagram tmp/appmap/minitest/Following_followers_page.sequence.uml
Enter fullscreen mode Exit fullscreen mode

请注意，该图表将作为*.sequence.uml文件打印在与 AppMap 文件相同的目录中。现在，我们将使用 PlantUML 将其转换为 SVG。

$ java -jar ~/Downloads/plantuml-1.2022.8.jar -tsvg tmp/appmap/minitest/Following_followers_page.sequence.uml
Enter fullscreen mode Exit fullscreen mode

检查文件是否存在：

$ ls tmp/appmap/minitest/Following_followers_page.sequence.svg       
tmp/appmap/minitest/Following_followers_page.sequence.svg
Enter fullscreen mode Exit fullscreen mode

在浏览器中打开：

$ open tmp/appmap/minitest/Following_followers_page.sequence.svg
Enter fullscreen mode Exit fullscreen mode

就是这样！当然，如果您愿意，您可以手动编辑 UML，并且可以将 UML 和 SVG 文件上传并共享到任何您喜欢的地方。

包起来

AppMap CLI@appland/appmap包含一个sequence-diagram命令，该命令可以根据 AppMap 数据（顺便说一下，数据是 JSON）生成 PlantUML 文本文件。PlantUML JAR 文件可以将该文本文件转换为 SVG（或其他格式，例如 PNG）。AppMap 扩展将所有这些工具整合到一个集成的 UI 体验中，让您可以轻松地持续编写代码、运行应用程序、编写测试、创建 AppMap、生成序列图并与团队共享。

现在就自己尝试一下吧！如果您有任何问题、想法或意见，欢迎加入AppMap Slack。我们期待您的反馈。

文章来源：https://dev.to/appmap/auto-magically-generate-sequence-diagrams-of-your-codes-runtime-behavior-597a
Devto 翻译
PREV
Next.js + 样式化组件简易指南 ▲ + 💅
NEXT
机器学习入门 - 第一部分