PlantUML 基础使用技术文档

摘要

[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 在线使用

官网：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
}

动态引用 ：支持包含外部文件 !include
Kroki API 渲染：无需本地安装，直接通过 REST API 渲染图片

8. 典型应用场景

技术架构文档
产品需求说明
API 调用流程
DevOps 持续集成文档
团队技术分享