Mermaid 与 PlantUML 类图：从 Markdown 画 UML

为什么用 Markdown 画 UML

UML 工具（Enterprise Architect、StarUML、Visio）的痛点：

商业授权贵
团队协作要共享文件
改一处要打开 GUI 拖拽

文本描述 UML 的方案：

Mermaid：2014 年起，GitHub 原生支持，类图/时序图/流程图 10+ 种
PlantUML：2009 年起，Java 实现，UML 2.5 全覆盖，扩展性最强

Mermaid

类图基础

classDiagram
    Animal <|-- Person
    Person <|.. Man

类图语法

classDiagram
    class Animal {
        +String name
        +int age
        +eat() void
        -breathe() void
    }
    class Person {
        +String id
        +think() void
    }
    class Man {
        +work() void
    }
    Animal <|-- Person  // 继承（实心空心三角箭头）
    Person <|.. Man    // 实现（虚线空心三角箭头）

关系符号

符号	含义
`<\|--`	继承（extends）
`<\|\..`	实现（implements）
`*--`	组合（Composition）
`o--`	聚合（Aggregation）
`-->`	关联（Association）
`..>`	依赖（Dependency）
`--`	实线链接
`..`	虚线链接

时序图

sequenceDiagram
    participant U as User
    participant A as App
    participant S as Server
    U->>A: 点击登录
    A->>S: POST /login {user, pass}
    S-->>A: 200 {token}
    A-->>U: 跳转到首页

流程图

flowchart TD
    A[开始] --> B{是否登录}
    B -- 是 --> C[首页]
    B -- 否 --> D[登录页]
    D --> E[提交登录]
    E --> F{验证成功}
    F -- 是 --> C
    F -- 否 --> G[错误提示]
    G --> D

状态图

stateDiagram-v2
    [*] --> 待支付
    待支付 --> 已支付: 付款
    已支付 --> 已发货: 发货
    已发货 --> 已签收: 签收
    已签收 --> [*]
    待支付 --> 已取消: 取消
    已取消 --> [*]

ER 图

erDiagram
    USER ||--o{ ORDER : places
    USER {
        int id PK
        string name
        string email
    }
    ORDER {
        int id PK
        int user_id FK
        date created_at
    }

GitHub 原生支持

1
2
3
4
5
# README.md
\`\`\`mermaid
classDiagram
    Animal <|-- Person
\`\`\`

GitHub 会自动渲染成 SVG。

IDEA 集成

IDEA Ultimate 内置 Mermaid 预览：

.md 文件里的 mermaid 代码块
或装 Mermaid 插件

VSCode 集成

装 Markdown Preview Mermaid Support 插件
Ctrl + Shift + V 预览

PlantUML

PlantUML 比 Mermaid 功能强，覆盖 UML 2.5 全套，扩展性更好。

安装

1
2
3
4
5
6
7
8
# Java JRE 8+
java -jar plantuml.jar file.puml

# VSCode 插件
# PlantUML (by jebbs)

# IDEA 插件
# PlantUML integration

类图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
@startuml
class Animal {
    +name: String
    +age: int
    +eat(): void
    -breathe(): void
}

class Person {
    +id: String
    +think(): void
}

class Man {
    +work(): void
}

Animal <|-- Person
Person <|.. Man
@enduml

关系

1
2
3
4
5
6
7
8
@startuml
A <|-- B           ' 继承
C <|.. D           ' 实现
E *-- F            ' 组合
G o-- H            ' 聚合
I --> J            ' 关联
K ..> L            ' 依赖
@enduml

时序图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
@startuml
actor User
participant "App" as A
participant "Server" as S

User -> A: 点击登录
A -> S: POST /login
S --> A: 200 {token}
A --> User: 跳转到首页
@enduml

流程图（活动图）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
@startuml
(*) --> "开始"
if "已登录" then
    -->[是] "首页"
    --> (*)
else
    -->[否] "登录页"
    --> "提交登录"
    if "验证成功" then
        -->[是] "首页"
    else
        -->[否] "错误提示"
    endif
endif
@enduml

状态图

1
2
3
4
5
6
7
8
@startuml
[*] --> 待支付
待支付 --> 已支付: 付款
已支付 --> 已发货: 发货
已发货 --> 已签收: 签收
已签收 --> [*]
待支付 --> 已取消: 取消
@enduml

组件图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
@startuml
package "Frontend" {
    [Web App]
    [Mobile App]
}

package "Backend" {
    [API Gateway]
    [Auth Service]
    [Order Service]
}

[Web App] --> [API Gateway]
[Mobile App] --> [API Gateway]
[API Gateway] --> [Auth Service]
[API Gateway] --> [Order Service]
@enduml

部署图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
@startuml
node "Web Server" {
    [Nginx]
    [App]
}

node "Database" {
    [MySQL]
    [Redis]
}

[Nginx] --> [App]
[App] --> [MySQL]
[App] --> [Redis]
@enduml

主题与样式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
@startuml
!theme plain
skinparam classAttributeIconSize 0
skinparam classFontSize 14
skinparam classBackgroundColor #F0F0F0

class Foo {
    +method()
}
@enduml

PlantUML Server

如果不想装 Java，可以用自己的 PlantUML Server：

1
2
3
4
5
# 官方
docker run -d -p 8080:8080 plantuml/plantuml-server

# 用法
curl "http://localhost:8080/svg/~1uml@somefile"

或者用公共 PlantUML 服务：https://www.plantuml.com/plantuml/uml/

Mermaid vs PlantUML 对比

维度	Mermaid	PlantUML
渲染	JS（前端）	Java
GitHub 原生	✅	❌（需插件）
类型覆盖	10+	UML 2.5 全
扩展性	一般	强（皮肤、宏）
主题	少	多
性能	较慢（前端渲染）	快（Java 服务端）
上手	简单	较难
输出	SVG	SVG/PNG/PDF

选 Mermaid 的场景：团队用 GitHub Wiki / README、简单图为主、JS 渲染方便 选 PlantUML 的场景：需要严格 UML、复杂时序图、企业级文档

工程化

文档生成器

docsify + Mermaid 插件
GitBook + Mermaid 插件
VuePress + Mermaid 插件
Docusaurus + Mermaid 插件（v3 内置）

CI/CD 集成

GitHub Action 自动校验 Mermaid 语法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# .github/workflows/mermaid-check.yml
name: Mermaid Check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: neenjaw/extract-mermaid-blocks-action@v1
        with:
          output-folder: 'mermaid-blocks'
      - uses: nicolegordon/mermaid-validate-action@v1
        with:
          input: 'mermaid-blocks'

IDE 实时预览

VSCode + Markdown Preview Enhanced：实时预览 Mermaid
IDEA + PlantUML Integration：右键 PlantUML 文件 → Show Preview
Obsidian：原生支持 Mermaid

下一步

想把类图转成代码，看 JetBrains MPS、UML Designer
想要画系统架构图，看 2017-08-15《iOS 应用开发与证书管理》中架构图部分
想要画 UI 原型，看 2014-05-15《Axure 产品原型设计》

参考资料

Mermaid 官方：https://mermaid.js.org/
Mermaid Live Editor：https://mermaid.live/
PlantUML 官方：https://plantuml.com/
PlantUML 中文文档：https://plantuml.com/zh/
PlantUML Server：https://github.com/plantuml/plantuml-server

2024+ 视角（从 Mermaid/PlantUML 到 AI 画图 + 架构即代码）

2015 年写 Mermaid/PlantUML 时，文本画图还是"新事物"；到 2024-2026 年，这两套已经全面成为行业标准，并出现明显分层：

GitHub 原生支持的扩散：
- Mermaid 仍是 GitHub/GitLab 默认渲染引擎
- GitLab 15+ 也支持 PlantUML 渲染
- Notion、飞书、语雀等均原生支持 Mermaid
Mermaid v10/v11 增强：
- 新增 C4 插件（Context/Container/Component）—— 配合 Structurizr 简化架构图
- Git graph 已成为最常被复制的图类型
- Architecture diagram（v10.6+）支持服务、数据库、队列等图标
PlantUML 的 C4-PlantUML 扩展：
- 第三方 C4-PlantUML 让 PlantUML 也能画 C4
- Mermaid 渲染 C4 性能 vs PlantUML 渲染 C4 性能：复杂 C4 图 Mermaid 仍偏慢
AI 画图崛起：
- Mermaid Chart + AI（自动从文字生成图）
- Eraser.io / Whimsical AI（手绘草图转 UML）
- GitHub Copilot Workspace 支持从 issue 描述自动生成架构图
Structurizr DSL 全面胜出"画架构图"场景：
- C4 模型 + Structurizr DSL（Java 生态）+ Structurizr Lite（本地预览）已是画系统架构的事实标准
- 替代品：Mermaid + C4 插件（轻量）、draw.io / diagrams.net（GUI 派）
文档工具集成：
- Docusaurus（v3+）内置 Mermaid
- Hugo + Mermaid 短代码
- VitePress / Astro 都默认支持 Mermaid
新工具涌现：
- Excalidraw（手绘风格，团队协作）
- tldraw（白板式画架构图）
- IcePanel（C4 互动式）
- Ilograph（多视角架构图）
PlantUML 的"危机"：
- 公共 PlantUML Server 经常因负载限速
- 私有 PlantUML Server + Asciidoctor Diagram 仍是企业内部方案
- 一些企业转向 D2（Terrastruct 出品，文本画图新秀，go 生态）

选型更新（2024 视角）：

场景	推荐工具
README/Wiki 简单图	Mermaid（GitHub 原生）
严格 UML（时序/状态/类）	PlantUML
系统架构 C4	Structurizr DSL（首选） / Mermaid C4 插件
手绘风格团队讨论	Excalidraw
互动式架构	IcePanel / Ilograph
AI 辅助	Mermaid Chart AI / Eraser AI
复杂企业文档	PlantUML Server + Asciidoctor

2015 年这篇的"Mermaid/PlantUML 对比"框架至今成立——GitHub 原生选 Mermaid，企业级严格 UML 选 PlantUML。变化的是 C4 模型成为架构图事实标准、AI 辅助画图崛起、私有 PlantUML Server 成为企业首选。