PlantUML 在团队协作中的 5 个真实用法

这篇文章总结把 PlantUML 真正用到团队里时，最常见的 5 个用法和踩坑点。

1. 用例图做需求评审

需求会上画 30 分钟白板，不如让大家回去花 30 分钟改一段 PlantUML —— 它能进 PR、可 diff、可评审。

@startuml
left to right direction
skinparam actorStyle awesome
actor "游客" as Guest
actor "会员" as Member
Member <<Human>>
rectangle "电商系统" {
  usecase "浏览商品" as UC1
  usecase "下单" as UC2
  usecase "支付" as UC3
  usecase "查看订单" as UC4
  usecase "申请退款" as UC5
}
Guest --> UC1
Member --> UC1
Member --> UC2
Member --> UC4
UC2 ..> UC3 : include
UC3 ..> UC5 : extend
@enduml

评审时 Reviewer 直接在 diff 里批注「应该 extend 而不是 include」，比对着白板照片来回解释快得多。

2. 组件图替代 PPT 架构图

组件图（C4-style）比 Visio 更适合放进仓库：

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(user, "用户", "前端 / 移动端")
Container(web, "Web App", "React/Vue", "用户操作界面")
Container(api, "API Service", "Go/Java", "对外 REST")
ContainerDb(db, "Primary DB", "PostgreSQL", "业务主库")
Container(redis, "Cache", "Redis", "热点缓存")

Rel(user, web, "使用")
Rel(web, api, "HTTPS/JSON", "3000 req/s")
Rel(api, db, "读写")
Rel(api, redis, "查询")
@enduml

源文件进 docs/architecture/，CI 自动出 PNG / SVG 附在 README。

3. PR 评审时贴时序图

复杂接口改动，光看代码看不明白，请在 PR 描述里加一段：

@startuml
title 旧版登录流程
participant FE
participant API
participant Auth
FE -> API: POST /login
API -> Auth: validate(jwt)
Auth --> API: ok
API -> API: 生成新的 session
API --> FE: 200 + Set-Cookie
@enduml

Reviewer 一眼看到第 4 步的 race condition —— 不用打开 IDE。

4. Onboarding 文档

新人入职第一天看 5 个 PlantUML 文件，比看 50 页 Confluence 快。每个模块一张组件图，几张关键路径的时序图。

5. CI 流水线图

用 PlantUML 渲染 GitHub Actions / Argo / Airflow 之类的流水线，让流水线图也可 diff：

@startuml
(*) --> "lint"
"lint" --> "test"
"test" --> "build"
"build" --> "deploy staging"
"deploy staging" --> "smoke test"
"smoke test" --> if "passed?" then
  -->[yes] "deploy prod"
  --> (*)
else
  -->[no] "alert oncall"
  --> "rollback"
  --> (*)
endif
@enduml

踩坑小提醒

用例图别加 rectangle 套 usecase 的双层结构：有些版本不支持。扁平写就好。
C4 plantuml 走 !include 远程资源：要么本地化，要么在 CI 里预先拉一份缓存。直接 fetch 经常被企业内网拦。
主题别和暗色网站打架：在公司 wiki 的暗色背景下，默认主题看不清，换 !theme cyborg 或 !theme black-knight。