PlantUML ER 图实战：从数据库设计到实体关系图

puml.online
  2026-08-08 10:00 2026-08-08 10:00 创建   2026-08-14 21:34:29 2026-08-14 21:34:29 更新    

ER 图（Entity Relationship Diagram，实体关系图）是数据库设计最重要的工具。用 PlantUML 画 ER 图，可以直接从数据库 schema 出图，也可以手画结构后交给团队 review。

ER 图是什么

ER 图描述实体（表）、属性（字段）、关系（外键约束）三者之间的关系。数据库设计初期用来理清概念，数据架构评审时用来对齐理解，重构时用来追踪影响。

常见场景：

  • 新项目启动：设计数据库 schema
  • 评审时：展示表结构和外键关系
  • 重构前：搞清楚表之间的依赖
  • 文档：给新成员看数据库全貌

一、最小例子

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
@startuml
entity "User" as user {
  +id: bigint PK
  --
  username: varchar(50)
  email: varchar(100)
  created_at: timestamp
}

entity "Post" as post {
  +id: bigint PK
  --
  +user_id: bigint FK
  title: varchar(200)
  body: text
  created_at: timestamp
}

user ||--o{ post: writes
@enduml

解释：

  • entity "显示名" as 别名 声明一个实体
  • { -- } 里面写字段，+ 前缀表示主键
  • ||--o{ 是关系基数符号（见下节）

二、关系基数（Cardinality）

ER 图的核心是关系基数——表示两个实体之间”一个 A 对应多少个 B”：

符号 含义 PlantUML 写法
` `
o{ 零或多个（zero or more） o{
`} ` 一个或多个（one or more）
`o ` 零或一个（zero or one）

组合起来：

1
2
3
4
5
6
7
8
@startuml
entity "User" as u
entity "Post" as p
entity "Comment" as c

u ||--o{ p : writes
p ||--o{ c : has
@enduml
  • User ||--o{ Post：一个 User 写零或多篇 Post（用户可以不写）
  • Post ||--o{ Comment：一篇 Post 有零或多条 Comment

三、实体声明语法

3.1 基本字段声明

1
2
3
4
5
6
7
entity "表名" as 别名 {
  +字段名: 类型  ← 主键（PK）
  ~字段名: 类型  ← 外键（FK）
  -字段名: 类型  ← 普通字段
  --               ← 分隔线（上方=主键，下方=其他）
  description: text
}

3.2 主键和外键

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@startuml
entity "orders" as orders {
  +order_id: bigint PK
  ~customer_id: bigint FK  ← ~ 表示外键
  ~product_id: bigint FK
  amount: decimal(10,2)
  status: varchar(20)
  created_at: timestamp
}

entity "customer" as c
entity "product" as p

c ||..o{ orders : places
p ||..o{ orders : contains
@enduml

.. 表示弱关系（dashed line），-- 表示强关系（solid line）。

3.3 完整的订单系统 ER

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
@startuml
hide circle
skinparam linetype ortho

entity "Customer" as cust {
  +customer_id: bigint PK
  --
  name: varchar(100)
  email: varchar(200)
  phone: varchar(20)
  created_at: timestamp
}

entity "Order" as ord {
  +order_id: bigint PK
  --
  +customer_id: bigint FK
  total_amount: decimal(12,2)
  status: varchar(20)
  order_date: date
}

entity "OrderItem" as item {
  +item_id: bigint PK
  --
  +order_id: bigint FK
  +product_id: bigint FK
  quantity: int
  unit_price: decimal(10,2)
}

entity "Product" as prod {
  +product_id: bigint PK
  --
  name: varchar(200)
  category: varchar(50)
  price: decimal(10,2)
  stock: int
}

cust ||--o{ ord : places
ord ||--o{ item : contains
prod ||--o{ item : "is in"
@enduml

hide circle 隐藏关系端点的圆点，skinparam linetype ortho 让线条垂直/水平走，更像标准 ER 图。

四、ER 图 vs 类图：什么时候用哪个

场景 用 ER 图 用类图
数据库 schema 设计 ✅ ❌
描述数据库表关系 ✅ ❌
ORM 实体建模 ✅ ✅
业务概念建模 ❌ ✅
服务间接口和数据结构 ❌ ✅
方法和行为 ❌ ✅

简单说：涉及数据库（表、字段、外键）→ ER 图；涉及代码结构（类、方法、接口）→ 类图。

五、实战：从数据库 Schema 直接出图

用 pg_dump 或 mysqldump 导出 schema，再用脚本转换成 PlantUML：

1
2
3
4
5
6
7
8
# PostgreSQL 导出 schema
pg_dump -h localhost -U postgres -d mydb \
  --schema-only --no-owner \
  | grep -E "^CREATE TABLE|^  [a-z].*|^ALTER TABLE|^  CONSTRAINT" \
  > schema_raw.txt

# 用 jq 解析（需要先转 JSON）
# 实际项目中用 sql2puml 或 dbml 的转换工具更靠谱

推荐工具链：

六、样式美化

6.1 隐藏字段（只显示表名和关系）

1
2
3
4
5
6
7
8
9
10
11
@startuml
hide methods
hide stereotypes

entity "User" as u
entity "Post" as p
entity "Comment" as c

u ||--o{ p
p ||--o{ c
@enduml

6.2 颜色编码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@startuml
skinparam entity {
  BackgroundColor #DarkSlateGray
  FontColor #ffffff
  BorderColor #2F4F4F
}

skinparam relationship {
  Color #A9A9A9
}

entity "User" as u
entity "Post" as p
u ||--o{ p
@enduml

6.3 垂直关系线

1
2
3
@startuml
skinparam linetype ortho
' 让关系线走水平和垂直，更整齐

七、常见报错

报错 原因 修复
Entity not found 引用了未声明的实体别名 检查 entity "X" as Y 的别名拼写
Duplicate identifier 同一实体声明了两次 合并或删除重复声明
关系箭头乱跑 默认 layout 问题 加 skinparam linetype ortho 或手动调位置

八、Mermaid ER 对比

Mermaid 也有 ER 图支持：

1
2
3
4
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    PRODUCT ||--o{ LINE-ITEM : "is in"
功能 PlantUML ER Mermaid ER
主键/外键标识 ✅ + / ~ ✅
关系基数 ✅ 完整 ✅ 部分
字段类型 ✅ 支持 ❌ 不支持
样式定制 ✅ 丰富 有限
嵌套实体 ✅ ❌

数据库设计阶段用 PlantUML（功能完整、样式丰富）；文档里快速画 ER 用 Mermaid（上手快，不需要 Java）。

小结

PlantUML ER 图记住 4 点：

  1. entity "显示" as ID { +pk: type / ~fk: type / -field: type } 是标准声明格式
  2. 关系基数：|| = 恰好一个，o{ = 零或多个，}| = 一个或多个
  3. skinparam linetype ortho 让关系线更整齐
  4. 数据库 schema 设计用 ER 图；代码结构用类图——别混用

ER 图是团队沟通数据库结构的通用语言，比文字描述准确 10 倍。

  • 标题: PlantUML ER 图实战：从数据库设计到实体关系图
  • 作者: puml.online
  • 创建于 : 2026-08-08 10:00:00
  • 更新于 : 2026-08-14 21:34:29
  • 链接: https://puml.online/blog/plantuml-er-diagram/
  • 版权声明: 本文章采用 CC BY-NC-SA 4.0 进行许可。
目录
PlantUML ER 图实战：从数据库设计到实体关系图
  1. ER 图是什么
  2. 一、最小例子
  3. 二、关系基数（Cardinality）
  4. 三、实体声明语法
    1. 3.1 基本字段声明
    2. 3.2 主键和外键
    3. 3.3 完整的订单系统 ER
  5. 四、ER 图 vs 类图：什么时候用哪个
  6. 五、实战：从数据库 Schema 直接出图
  7. 六、样式美化
    1. 6.1 隐藏字段（只显示表名和关系）
    2. 6.2 颜色编码
    3. 6.3 垂直关系线
  8. 七、常见报错
  9. 八、Mermaid ER 对比
  10. 小结