目录
[1. 什么是 PlantUML](#1. 什么是 PlantUML)
[2. 安装与环境配置](#2. 安装与环境配置)
[2.1 本地使用](#2.1 本地使用)
[2.2 在线使用](#2.2 在线使用)
[3. 基本语法](#3. 基本语法)
[3.1 示例:系统架构图](#3.1 示例:系统架构图)
[3.2 常用元素](#3.2 常用元素)
[4. 渲染方式](#4. 渲染方式)
[4.1 VSCode](#4.1 VSCode)
[4.2 在线渲染](#4.2 在线渲染)
[4.3 生成图片](#4.3 生成图片)
[5. 推荐实践](#5. 推荐实践)
[6. 常见图类型](#6. 常见图类型)
[7. 进阶功能](#7. 进阶功能)
[8. 典型应用场景](#8. 典型应用场景)
摘要
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 在线使用
-
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 }
-
动态引用 :支持包含外部文件
!include
-
Kroki API 渲染:无需本地安装,直接通过 REST API 渲染图片
8. 典型应用场景
-
技术架构文档
-
产品需求说明
-
API 调用流程
-
DevOps 持续集成文档
-
团队技术分享