PlantUML 入门与实战指南

原创已于 2025-10-25 11:34:11 修改 · 1.1k 阅读

14 ·

CC 4.0 BY-SA版权

文章标签：

#uml

于 2025-10-25 11:29:16 首次发布

工具专栏收录该内容

2 篇文章

订阅专栏

在软件开发过程中，UML（统一建模语言）是一种常用的建模工具，用于表示系统的结构和行为。然而，传统的 UML 绘图工具如 Enterprise Architect、Visio 等需要手动拖拽，效率不高。PlantUML 则是一种基于文本的 UML 绘图工具，通过简单的文本描述即可生成 UML 图，极大提高了绘图效率。

本文将从入门到进阶，全面介绍 PlantUML 的使用方法。

1. 什么是 PlantUML

PlantUML 是一款开源工具，它通过解析特定语法的文本文件，自动生成 UML 图。它支持多种 UML 图类型，包括：

类图（Class Diagram）
时序图（Sequence Diagram）
用例图（Use Case Diagram）
活动图（Activity Diagram）
组件图（Component Diagram）
状态图（State Diagram）
对象图（Object Diagram）
部署图（Deployment Diagram）

PlantUML 的特点：

文本化：只需写文本，无需手动拖拽。
易版本管理：文本文件可以放入 Git 版本控制。
支持多种导出：可生成 PNG、SVG、PDF 等格式。
可嵌入文档：支持 Markdown、Confluence、Asciidoc 等。

2. PlantUML 安装与使用

2.1 安装方式

在线使用
访问 PlantUML 官方在线编辑器，无需安装，直接编写即可生成 UML 图。
本地安装
- 下载 PlantUML jar 文件：https://plantuml.com/zh/download
- 运行命令生成图：
```
java -jar plantuml.jar example.puml
```
- 支持生成 PNG、SVG 文件。
集成到 IDE
- VSCode：安装 PlantUML 插件，支持实时预览。
- IntelliJ IDEA：安装 PlantUML Integration 插件。
- Markdown：VSCode + Markdown Preview Enhanced 支持 PlantUML 渲染。

3. PlantUML 基础语法

3.1 类图示例

@startuml
class User {
    - id: int
    - name: String
    + login()
    + logout()
}

class Admin extends User {
    + manageUsers()
}

User "1" -- "0..*" Order : places >
Order o-- "1" Product : contains >
@enduml

说明：

class 定义类。
- 表示私有属性，+ 表示公共方法。
extends 表示继承关系。
-- 表示关联关系，o-- 表示组合关系。
* 表示多重性。

生成效果如下（可在 PlantUML 工具中预览）：

User <-- Admin
User "1" -- "0..*" Order
Order o-- "1" Product

3.2 时序图示例

@startuml
actor User
participant "Web App" as Web
participant "Server" as S

User -> Web : Login
Web -> S : Validate Credentials
S --> Web : Success
Web --> User : Welcome Page
@enduml

说明：

actor 定义参与者。
participant 定义对象/组件。
-> 表示消息发送，--> 表示返回。

3.3 活动图示例

@startuml
start
:User login;
if (valid credentials?) then (yes)
  :Show dashboard;
else (no)
  :Show error message;
endif
stop
@enduml

说明：

start 和 stop 定义流程起止。
: 定义流程步骤。
if / else / endif 定义分支。

4. PlantUML 高级特性

4.1 样式与主题

可以自定义颜色、字体、箭头样式等：

@startuml
skinparam class {
    BackgroundColor PaleGreen
    ArrowColor DarkGreen
    BorderColor DarkGreen
}
class Example
@enduml

4.2 使用宏和组件化

支持 !define 定义宏。
可拆分多个 .puml 文件，通过 !include 引入复用。

!define ENTITY(name) class name << (E,#FFAAAA) >>
ENTITY(User)
ENTITY(Order)

4.3 集成版本控制与文档

将 PlantUML 文件放入 Git，可自动追踪 UML 图修改历史。
可在 Markdown 中直接嵌入 PlantUML 代码块：
```
@startuml
Alice -> Bob: Hello
@enduml
```

5. PlantUML 实际应用场景

软件架构设计：通过类图、组件图、部署图规划系统结构。
接口文档：利用时序图描述 API 调用流程。
团队协作：文本化 UML 支持多人协作修改，避免拖拽式工具的版本冲突。
文档自动化：结合 Markdown、Confluence、GitLab Wiki，自动生成文档。

6. 注意事项

图形复杂时：大型类图可能难以通过文本管理，建议拆分。
性能问题：本地渲染复杂图形时可能较慢，可考虑生成 SVG。
与 UML 标准：PlantUML 不是 100% UML 标准，但足够覆盖日常使用需求。

7. 总结

PlantUML 是一款高效、灵活、可版本化的 UML 绘图工具，非常适合软件开发团队。掌握 PlantUML 不仅能提高文档编写效率，还能让团队更直观地理解系统架构和业务流程。