用 PlantUML 把图放进 PR 评审

PR 评审里图往往被遗漏，因为大多数团队把图放在 Confluence 或者 PPT 里。这篇讲怎么把 PlantUML 当代码一样放进 PR。

为什么不把图放进 PR

最常见的几个借口：

• 「图是设计阶段画的，开发评审不动」
• 「图很大、牵一发动全身，合并时容易漏」
• 「评审系统看不到图，没有评审意义」

这些借口在 PlantUML + GitHub/GitLab 渲染器面前都不成立。

仓库布局建议

1
2
3
4
5
6
7
8
9
10

docs/
  architecture/
    system.puml          # 全景图
    service-a.puml       # 服务 A
    service-b.puml       # 服务 B
  sequences/
    login.puml
    checkout.puml
    refund.puml
  README.md

每张图一个 .puml 文件。文件命名用 kebab-case。

PR 描述里嵌入

1
2
3
4
5
6
7

## 修改

修复登录超时重试导致 session 反复重置的问题。

### 修改前

![alt](./docs/sequences/login.puml)

或者直接用 markdown image link：

1

![login flow](https://www.plantuml.com/plantuml/svg/<encoded>)

GitHub 支持 <encoded> 直接渲染。GitLab 也支持。这样 PR 描述里就有图了。

让 GitHub/GitLab 渲染 .puml

GitHub 不直接渲染 .puml 后缀的源文件。.puml 是文本 source，需要先转 SVG/PNG 才能嵌入。两个思路：

A. 在 PR 里加 SVG 资源（推荐）

1
2

# 在本地渲染一遍
java -jar plantuml.jar -tsvg docs/sequences/login.puml

每次改 .puml 提交时，把渲染好的 .svg 也提交。.puml 走 diff，.svg 走渲染产物。

用 .gitattributes 标记 SVG 为 diff=image 让 PR diff 自动出图：

1

docs/**/*.svg diff=image

B. 在仓库里放渲染脚本

1
2
3
4
5
6

#!/bin/bash
# scripts/render-uml.sh
set -e
for f in $(find docs -name '*.puml'); do
  java -jar plantuml.jar -tsvg -failfast2 -nometadata "$f"
done

在 CI 里跑：

1
2
3
4
5
6
7
8
9
10

# GitHub Actions 示例
- name: Render PlantUML
  run: bash scripts/render-uml.sh
- name: Commit rendered SVGs
  run: |
    git config user.name github-actions
    git config user.email github-actions@github.com
    git add docs/**/*.svg
    git commit -m "render: regenerate SVGs" || exit 0
    git push

这样 PR 里能 diff SVG，评审也能用 GitHub 的 SVG diff viewer 看修改前后。

在 PR 模板里强制加图

.github/PULL_REQUEST_TEMPLATE.md：

1
2
3
4
5
6
7
8
9
10

## 改动

<!-- 描述这部分做了什么 -->

## 图

<!-- 如果这个 PR 涉及接口、状态、流程改动，请添加/更新对应的 .puml，并提交对应 SVG -->
- [ ] 我已添加/更新了相关的 .puml 文件
- [ ] 我已重新渲染了对应的 SVG
- [ ] 我已在下方附上相关图（可使用 plantuml 服务器渲染实时链接或本地 SVG）

这样评审者一眼看到图。

评审图本身

评审者应该在 PR 评论里写：

“这个时序图第 4 步和第 5 步之间为什么没有箭头？是同步阻塞还是异步？”

而不是：

“我们开个会聊聊登录流程”

让评审发生在可见、可搜索、可追溯的文本流里。

工具搭配建议

实战工作流

我目前在用：

1. 在 .puml 文件里写
2. VSCode PlantUML extension 实时预览
3. 提交时同时 commit .puml 和渲染好的 .svg
4. CI 自动重渲染 SVG 并 commit 回来（如果本地忘跑了）
5. PR 描述里用 plantuml.com 编码 URL 或者本地 SVG path
6. 评审者直接在 SVG 上批注

踩坑提示

• PlantUML 服务器 URL 在 PR 渲染时延迟 1-2 秒：PR 描述里用 plantuml.com URL 时，GitHub 预览渲染 markdown 比较慢，URL 后面的图片可能要点开 PR 才能看到。可以提前渲染 SVG 替代。
• CJK 字体在 SVG 里失效：plantuml.jar 默认用 OpenJDK 字体，CJK 字符常常渲染成方块。配置 plantuml.config 或者 -config 选项指定中文字体：

  1 2 3

  java -Djava.awt.headless=true -jar plantuml.jar \ -config scripts/plantuml.cfg \ -tsvg docs/sequences/login.puml

  plantuml.cfg 内容：

  1 2	skinparam defaultFontName "PingFang SC" skinparam defaultFontSize 14

• 不要把 .puml 源 commit 拆开：一张图就是一个文件，拆成多个 diagram 让评审只能看部分，看不到整体。
• 主题和暗色模式要小心：默认主题在 GitHub 暗色模式下太亮，可以加 !theme cyborg 或者 !theme black-knight，但反之在白底也很突兀。最稳的是用 !theme plain 加自定义 skinparam。