plantuml-syntax

PlantUML 语法参考

概述

PlantUML 是一款基于 Java 的工具，可根据文本描述创建图表。它支持全面的 UML 图表以及许多非 UML 图表类型。

主要优势：

• 图表类型支持最全面（15+ 种）
• 成熟的 C4 模型集成，支持图标和精灵图
• 丰富的自定义选项
• 经受实战检验（自 2009 年起）

要求：

• Java 运行时环境（JRE）
• GraphViz（部分图表类型需要）
• 或使用 Docker：docker run -p 8080:8080 plantuml/plantuml-server

---

图表类型速查

UML 图表

类型	关键字	适用场景
时序图	@startuml	交互、API 流程、协议
用例图	@startuml	需求、用户故事
类图	@startuml	OOP 设计、领域模型
活动图	@startuml	工作流、流程
组件图	@startuml	系统结构
部署图	@startuml	基础设施、部署
状态图	@startuml	状态机

非 UML 图表

类型	关键字	适用场景
JSON	@startjson	JSON 结构可视化
YAML	@startyaml	YAML 结构可视化
线框图	@startsalt	UI 模型图
甘特图	@startgantt	项目时间线
思维导图	@startmindmap	层级化想法
WBS	@startwbs	工作分解
ER 图	@startuml	数据库架构
C4	使用 C4 include 的 @startuml	软件架构

---

基本语法

所有 PlantUML 图表都由开始和结束标签包裹：

@startuml
' Your diagram code here
@enduml

注释：

• 单行：' This is a comment
• 块：/' This is a block comment '/

标题和说明文字：

@startuml
title My Diagram Title
caption This is a caption
header Page Header
footer Page Footer

' Diagram content
@enduml

---

速查卡

时序图

@startuml
participant A
participant B
A -> B: Message
A <-- B: Response
@enduml

类图

@startuml
class Name {
    - private
    + public
    + method()
}
A <|-- B : extends
A *-- B : contains
@enduml

活动图

@startuml
start
:Action;
if (condition?) then (yes)
    :True path;
else (no)
    :False path;
endif
stop
@enduml

状态图

@startuml
[*] --> State1
State1 --> State2 : event
State2 --> [*]
@enduml

组件图

@startuml
[Component1] --> [Component2]
database DB
Component2 --> DB
@enduml

---

参考资料

如需详细语法和完整示例，请参阅：

参考资料	内容	加载时机
sequence.md	参与者、箭头、激活、分组、注释	创建时序图时
class.md	类、可见性、关系、基数	创建类图时
activity.md	条件、泳道、分支/汇合	创建活动图时
state-component.md	状态机、组件、部署	创建状态图/组件图时
c4.md	C4 上下文图、容器图、组件图	创建 C4 架构图时
special-diagrams.md	ER 图、JSON、思维导图、甘特图	创建非 UML 图表时
styling-setup.md	Skinparam、主题、安装	自定义图表、设置 PlantUML 时

---

文件扩展名

扩展名	说明
.puml	标准 PlantUML 文件
.plantuml	备用扩展名
.pu	短扩展名
.iuml	Include 文件

---

测试场景

场景 1：创建时序图

查询：“为用户身份验证创建一个 PlantUML 时序图”

**预期：**技能已激活，提供包含参与者、箭头和 alt/else 块的时序图语法

场景 2：创建类图

查询：“为电子商务领域生成一个 PlantUML 类图”

**预期：**技能已激活，提供包含关系和基数的类图语法

场景 3：创建 C4 图

查询：“用 PlantUML 创建一个 C4 容器图”

**预期：**技能已激活，引导用户参阅 c4.md，了解 include 和语法

---

**最后更新：**2025-12-28 **PlantUML 版本：**1.2024.6

版本历史

• v1.1.0（2025-12-28）：重构为渐进式披露，将内容提取到 references/ 中
• v1.0.0（2025-12-26）：首次发布