目录
摘要
PlantUML 是一款基于文本的图形绘制工具，支持用简单、直观的语法绘制架构图、流程图、用例图等常见技术图形。它支持本地渲染、集成开发环境（IDE）插件、以及在线渲染服务，广泛应用于技术文档、设计评审、DevOps CI/CD 等场景。本手册介绍 PlantUML 的基本使用方法、开发环境配置、常见图形语法和推荐实践，适用于开发、测试、运维、产品等岗位。
1. 什么是 PlantUML
基于文本的图形绘制工具；
支持 架构图、流程图、状态图、部署图、类图、时序图等；
语法简单，适合版本管理、多人协作。
2. 安装与环境配置
2.1 本地使用
| 工具 | 安装方式 |
|---|---|
| VSCode | 安装插件：PlantUML、需要 Java 运行环境 |
| IntelliJ IDEA | 安装 PlantUML Integration 插件 |
| Typora / Obsidian | 内置或插件支持直接渲染 |
| 命令行 | 安装 Graphviz + Java，使用 plantuml.jar 渲染 |
2.2 在线使用
官网：https://www.plantuml.com/plantuml
API 服务：Kroki!
GitLab / GitHub Pages：通过 CI 直接生成
3. 基本语法
3.1 示例：系统架构图
@startuml
actor 用户 as User
rectangle "管理页面" as Astro {
[登录页面]
[用户管理]
[设备管理]
}
rectangle "核心模块" as Core {
[权限管理]
[业务逻辑]
}
database "物联网平台" as IoTDA
User --> Astro : 登录 / 操作
Astro --> Core : API 调用
Core --> IoTDA : 获取设备数据
@enduml
3.2 常用元素
| 元素类型 | 语法示例 |
|---|---|
| 角色 | actor 用户 as User |
| 模块 | rectangle "模块名称" as Module |
| 数据库 | database "名称" as DB |
| 箭头 | A --> B : 调用 / 传输 |
| 分组 | package "模块组" ... end package |
4. 渲染方式
4.1 VSCode
安装 “PlantUML” 插件
打开
.puml文件，右键选择 "Preview Current Diagram"
4.2 在线渲染
复制完整代码到 PlantUML 官网
点击 “Refresh” 渲染图形
4.3 生成图片
本地命令行运行：
java -jar plantuml.jar diagram.puml可输出 PNG / SVG / PDF
5. 推荐实践
| 场景 | 推荐做法 |
|---|---|
| 版本管理 | 将 .puml 文件纳入 Git 版本管理 |
| 多人协作 | 使用文本形式，便于代码评审 |
| 自动文档生成 | 配合 CI 工具生成 PNG / HTML 文档 |
| 图形复杂度控制 | 每张图尽量不超过 20 个模块 |
6. 常见图类型
| 图类型 | 关键语法 |
|---|---|
| 架构图 | rectangle、database |
| 用例图 | actor、usecase |
| 流程图 | start、if、repeat |
| 时序图 | participant、->> |
| 状态图 | state |
| 类图 | class、interface |
| 部署图 | node、artifact |
7. 进阶功能
样式优化：
skinparam backgroundColor #F5F5F5 skinparam rectangle { BackgroundColor #FFFFFF BorderColor #999999 }动态引用：支持包含外部文件
!includeKroki API 渲染：无需本地安装，直接通过 REST API 渲染图片
8. 典型应用场景
技术架构文档
产品需求说明
API 调用流程
DevOps 持续集成文档
团队技术分享