1. PlantUML 简介
PlantUML 是一个开源的工具,用于通过简单的文本描述生成各种类型的 UML(统一建模语言)图表和其他可视化图形。它由 Arnaud Roques 在 2009 年首次发布,旨在为开发人员、架构师和业务分析师提供一种轻量级、高效的方式来创建图表。PlantUML 的核心理念是将复杂的图形建模转化为直观的文本描述,降低创建和维护图表的门槛。
PlantUML 支持多种图表类型,包括但不限于:
- UML 图:类图、用例图、时序图、活动图、组件图、部署图、状态图、对象图。
- 非 UML 图:架构图、流程图、Gantt 图、思维导图、ER 图等。
- 其他:JSON/YAML 数据可视化、ASCII 艺术图。
其最大的特点是基于纯文本的语法,易于版本控制、分享和自动化生成,特别适合软件开发和文档编写场景。
2. 为什么选择 PlantUML?
PlantUML 在众多建模工具中脱颖而出,原因如下:
- 文本驱动:通过简单的文本语法定义图表,无需使用复杂的图形界面。文本文件易于存储在 Git 等版本控制系统中,方便团队协作和历史追踪。
- 跨平台支持:PlantUML 可通过命令行、在线编辑器、IDE 插件(如 VS Code、IntelliJ、Eclipse)或 CI/CD 管道运行,适应多种工作环境。
- 高效快速:相比传统拖拽式工具,PlantUML 的文本语法更适合快速原型设计和迭代,生成图表仅需几秒。
- 开源免费:PlantUML 是完全免费的开源项目,拥有活跃的社区支持和丰富的文档。
- 高度集成:可与 Markdown、LaTeX、Doxygen 等工具无缝集成,生成的图表可直接嵌入技术文档或网页。
- 轻量级:无需安装复杂软件,仅需 Java 和 Graphviz(用于图形渲染)即可运行。
3. PlantUML 的安装与配置
3.1 本地安装
-
安装依赖:
- 确保系统已安装 Java(JRE 或 JDK)。
- 安装 Graphviz(用于渲染图形),可在官网(graphviz.org)下载或通过包管理器安装(如(-fi1hi11ag4ghwhisf8wvpy4cfxuy75b7bv47ak3b/)
apt install graphviz
或brew install graphviz
)。
-
下载 PlantUML:
- 从 GitHub(github.com/plantuml/pl...
plantuml.jar
文件。
- 从 GitHub(github.com/plantuml/pl...
-
运行 PlantUML:
- 使用命令行运行:
java -jar plantuml.jar 文件名.puml
,将生成对应的图表文件(默认 PNG 格式)。 - 支持输出多种格式(如 SVG、PDF、ASCII):
java -jar plantuml.jar -tsvg 文件名.puml
。
- 使用命令行运行:
3.2 在线使用
无需安装任何软件,可直接访问 PlantUML 官方在线编辑器(www.plantuml.com/plantuml)。用... PlantUML 代码,即可实时预览图表,并支持导出为图片或分享链接。
3.3 IDE 集成
许多主流 IDE 提供 PlantUML 插件,推荐如下:
- VS Code:安装 "PlantUML" 插件(由 jebbs),支持实时预览、导出和语法高亮。
- IntelliJ IDEA:安装 "PlantUML Integration" 插件,适合 Java 开发者。
- Eclipse:安装 "PlantUML" 插件,适合企业级开发环境。
3.4 CI/CD 集成
PlantUML 可集成到持续集成管道中,自动生成图表。例如:
- 在 GitHub Actions 中使用 PlantUML Action,自动将
.puml
文件转换为图片并嵌入文档。 - 使用 Docker 镜像(如
plantuml/plantuml
)在 CI 环境中运行 PlantUML。
4. PlantUML 语法详解
PlantUML 使用 @startuml
和 @enduml
包裹图表定义,语法简洁且基于关键字。以下是几种常见图表的语法示例。
4.1 时序图(Sequence Diagram)
用于展示对象之间的消息交互顺序。例如:

less
@startuml
actor User
participant "Web Server" as Server
User -> Server: 发送登录请求
Server -> Database: 查询用户信息
Database --> Server: 返回用户数据
Server --> User: 登录成功
note right: 登录失败时显示错误
@enduml
- 关键字:
actor
(表示外部实体)、participant
(表示系统组件)、->
(消息发送)、-->
(异步消息或返回值)、note
(添加注释)。
4.2 泳道图(Swim Diagram)
用于展示对象之间的消息交互顺序。例如:

css
@startuml
|用户|
start
:填写申请;
|主管|
:初审;
|经理|
:复审;
|用户|
:收到审批结果;
stop
@enduml
4.3 类图(Class Diagram)
用于描述类、接口及其关系。例如:

scss
@startuml
class Car {
-String model
-int speed
+startEngine()
+stopEngine()
}
class Engine {
-int horsepower
+ignite()
}
Car "1" --> "1" Engine : contains
interface Vehicle {
+drive()
}
Car ..|> Vehicle
@enduml
- 关键字:
class
、interface
、-->
(关联)、..|>
(实现接口)、+
(公共)、-
(私有)、*
(组合)、o
(聚合)。
4.4 活动图(Activity Diagram)
用于建模业务流程或系统工作流。例如:

scss
@startuml
start
:用户输入用户名和密码;
if (验证通过?) then (yes)
:显示主页;
while (用户未退出?) is (yes)
:处理用户操作;
endwhile
else (no)
:显示错误提示;
:返回登录页面;
endif
stop
@enduml
- 关键字:
start
、stop
、if
、then
、else
、while
、is
。
4.5 用例图(Use Case Diagram)
用于展示系统功能和用户交互。例如:

less
@startuml
actor Customer
actor Admin
Customer --> (View Products)
Customer --> (Place Order)
Admin --> (Manage Inventory)
(Manage Inventory) .> (View Products) : <<extend>>
@enduml
- 关键字:
actor
、-->
(关联)、.>
(扩展关系)、<<extend>>
。
4.6 其他图表
-
部署图:描述系统硬件和软件的部署结构。
less@startuml node "Web Server" { [Application] --> [Database] } [Web Server] --> [Load Balancer] @enduml
-
Gantt 图:用于项目计划和时间管理。
less@startgantt [Task 1] lasts 10 days [Task 2] starts at [Task 1]'s end and lasts 5 days @endgantt
5. 高级功能
5.1 样式自定义
PlantUML 支持通过 skinparam
自定义图表样式。例如:
scss
@startuml
skinparam monochrome true
skinparam classBackgroundColor LightYellow
skinparam classBorderColor Black
class Example {
+method()
}
@enduml
- 可自定义颜色、字体、边框、阴影等。
5.2 包含外部文件
支持通过 !include
关键字复用公共定义。例如:
less
@startuml
!include common.puml
class MyClass
@enduml
5.3 小清新配色分享
less
基础主题和样式
!theme plain
skinparam backgroundColor #E8F8F5 '薄荷绿主背景'
skinparam roundCorner 20
skinparam defaultFontName "Microsoft YaHei"
skinparam shadowing false
' 统一配色方案
skinparam {
ArrowColor #7FDBFF '浅蓝箭头'
ArrowThickness 2
BorderColor #A3E4D7 '浅绿边框'
BorderThickness 2
FontColor #34495E '深灰字体'
AttributeFontColor #7F8C8D
StereotypeFontColor #7F8C8D
BackgroundColor #E8F8F5 '薄荷绿主背景'
}
' 类图样式
skinparam class {
BackgroundColor #D6EAF8 '浅蓝'
BorderColor #A3E4D7 '浅绿'
BorderThickness 2
FontColor #34495E
AttributeFontColor #7F8C8D
StereotypeFontColor #7F8C8D
}
' 包样式
skinparam package {
BackgroundColor #FCF3CF '淡黄'
BorderColor #F9E79F '浅黄边框'
FontColor #34495E
BorderThickness 2
}
' 接口样式
skinparam interface {
BackgroundColor #D1F2EB '浅绿'
BorderColor #76D7C4 '薄荷绿边框'
FontColor #34495E
}
' 数据库样式
skinparam database {
BackgroundColor #F9E79F '淡黄'
BorderColor #F7DC6F '亮黄边框'
FontColor #34495E
}
' 箭头样式
skinparam arrow {
Color #7FDBFF '浅蓝'
FontColor #34495E
Thickness 2
}
' 时序图样式
skinparam sequence {
ArrowColor #7FDBFF
ArrowThickness 2
LifeLineBorderColor #A3E4D7
LifeLineBackgroundColor #E8F8F5
ParticipantBorderColor #A3E4D7
ParticipantBackgroundColor #D6EAF8
ParticipantFontColor #34495E
ActorBorderColor #A3E4D7
ActorBackgroundColor #D1F2EB
BoxBorderColor #76D7C4
BoxBackgroundColor #D1F2EB
DividerBackgroundColor #FCF3CF
DividerBorderColor #F9E79F
GroupBackgroundColor #FCF3CF
GroupBorderColor #F9E79F
GroupFontColor #34495E
}
' 状态图样式
skinparam state {
BackgroundColor #D6EAF8
BorderColor #A3E4D7
FontColor #34495E
StartColor #76D7C4
EndColor #F7DC6F
AttributeFontColor #7F8C8D
}
' 用例图样式
skinparam usecase {
BackgroundColor #D1F2EB
BorderColor #76D7C4
FontColor #34495E
}
' 活动图样式
skinparam activity {
BackgroundColor #D6EAF8
BorderColor #A3E4D7
FontColor #34495E
DiamondBackgroundColor #FCF3CF
DiamondBorderColor #F9E79F
}
skinparam component {
BackgroundColor #D6EAF8
BorderColor #7FDBFF
FontColor #34495E
}
skinparam database {
BackgroundColor #F9E79F
BorderColor #F7DC6F
FontColor #34495E
}
skinparam note {
BackgroundColor #FCF3CF
BorderColor #F9E79F
FontColor #34495E
}
' 立体样式
skinparam stereotypePosition right
skinparam stereotypeAlignment center
' 泳道图(Swimlane)样式
skinparam activity {
BackgroundColor #D1F2EB
BorderColor #A3E4D7
FontColor #34495E
DiamondBackgroundColor #FCF3CF
DiamondBorderColor #F9E79F
}
skinparam swimlane {
BackgroundColor #D1F2EB
BorderColor #A3E4D7
FontColor #34495E
TitleBackgroundColor #76D7C4
TitleFontColor #FFFFFF
}
skinparam partition {
BackgroundColor #D6EAF8
BorderColor #F9E79F
}
' skinparam legend {
' BackgroundColor #FFA726
' }
6. 实际应用场景
- 软件设计:快速绘制系统架构图、类图、时序图,用于需求分析和设计评审。
- 技术文档:在 Markdown 或 Wiki 中嵌入 PlantUML 图表,提升文档可读性和专业性。
- 团队协作:通过文本分享图表定义,结合 Git 进行版本管理和代码审查。
- 敏捷开发:在 Sprint 规划中绘制流程图或用例图,辅助用户故事定义。
- 教学与培训:通过直观的图表讲解复杂系统或流程,适合课堂或技术分享。
- 项目管理:使用 Gantt 图规划项目进度,清晰展示任务依赖和时间线。
7. 优势与局限性
7.1 优势
- 简单易学:语法直观,普通开发者可在数小时内上手。
- 版本控制友好:文本文件便于 diff 和 merge,适合团队协作。
- 自动化支持:易于集成到 CI/CD 流程,自动生成最新图表。
- 多图表支持:覆盖 UML 和非 UML 图表,适用场景广泛。
- 社区活跃:拥有丰富的教程、示例和插件支持。
7.2 局限性
- 复杂图表维护成本高:当图表元素过多时,文本描述可能变得冗长,难以维护。
- 样式自定义有限:相比专业设计工具(如 Visio),PlantUML 的图形样式较为简朴。
- 依赖 Graphviz:渲染复杂图表时可能需要优化 Graphviz 配置。
- 学习曲线:对于非技术人员,文本语法可能不如拖拽式工具直观。
8. 常见问题与解决方案
- 问题 :运行 PlantUML 时提示缺少 Graphviz。
解决 :确保安装 Graphviz 并配置环境变量(如将dot
命令添加到 PATH)。 - 问题 :中文字符显示为方框。
解决 :确保.puml
文件使用 UTF-8 编码,并在系统中安装支持中文的字体。 - 问题 :图表布局不美观。
解决 :调整skinparam
参数或使用!pragma layout smetana
切换布局引擎。 - 问题 :生成图片分辨率过低。
解决 :使用-Dplantuml.scale=2
提高输出分辨率。
9. 资源与学习途径
-
GitHub 仓库 :github.com/plantuml/pl...
-
教程与博客:
- PlantUML 官方 Wiki(plantuml.com/faq)。
- 社区博客(如 Baeldung 的 PlantUML 教程)。
-
示例库:PlantUML 官网提供大量示例代码,覆盖各种图表类型。
-
社区支持:通过 GitHub Issues 或 Stack Overflow 获取帮助。
10. 总结
PlantUML 是一个功能强大、轻量级的图表生成工具,以其文本驱动和跨平台特性在软件开发和文档编写中占据重要地位。它不仅简化了 UML 图表的创建过程,还支持多种非 UML 图表,满足多样化的可视化需求。对于希望提升设计效率、优化文档质量或实现自动化图表生成的团队,PlantUML 是一个不可多得的选择。
无论你是开发者、架构师还是项目经理,PlantUML 都能帮助你以更直观的方式表达复杂概念。赶快尝试 PlantUML,开启高效建模之旅吧!