plantUML使用指南

目录

• 什么是PlantUML
• 语法入门
  • PlantUML文档生成步骤
    • 添加注释
    • 箭头注向
    • 使用html
    • 设置BOX
    • 查看可用的图式组件
• 复杂图式
  • 简介
    • 时序图
    • 用例图
    • 类图
    • 对象图
    • 活动图 (旧版语法在此处)
    • 组件图
    • 部署图
    • 状态图
    • 定时图
    • JSON 数据
    • YAML 数据
    • 网络图 (nwdiag)
    • 线框图形界面
    • 架构图
    • 规范和描述语言 (SDL)
    • Ditaa 图
    • 甘特图
    • 思维导图
    • 工作分解图
    • 实体关系图
  • 学习使用
    • 使用 Sublime + PlantUML 高效地画图
    • 在线编辑器 + VS CODE使用
    • 在 VS Code中安装Markdown Preview Enhanced插件后，在Mrakdown使用PlantUML语法画相关UML图的不显示的问题
    • 其它教学

什么是PlantUML

PlantUML是一个快速创建UML图形的组件，官网上之所以称它是一个组件，我 想主要是因为多数情况下我们都是在Eclipse、NetBenas、Intellijidea、 Emacs、Word等软件里来使用PlantUML。

官方地址：https://plantuml.com/zh/
官方教程：https://plantuml.com/zh/guide

PlantUML支持的图形有：
sequence diagram, use case diagram, class diagram, activity diagram (here is the new syntax), component diagram, state diagram, object diagram, wireframe graphical interface

语法入门

https://www.cnblogs.com/young-youth/p/11665573.html

一个入门的例子（规范写法）

点这里查看源码

@startuml

' 定义样式
skinparam monochrome false
skinparam componentStyle rectangle
skinparam nodeBackgroundColor #E8F4F8
skinparam componentBackgroundColor #F0F8FF
skinparam artifactBackgroundColor #FFF8DC

' 数据源（节点表示物理/逻辑数据源）
node "数据库A\n(PostgreSQL)" as DB_A
node "日志文件\n(CSV格式)" as Log_File
node "API服务\n(REST)" as API_Service
node "消息队列\n(Kafka)" as Kafka_Queue

' 提取函数（组件表示可执行函数）
component "函数A1\n(查询表数据)" as Func_A1
component "函数A2\n(统计聚合)" as Func_A2
component "函数B1\n(解析CSV)" as Func_B1
component "函数C1\n(GET请求)" as Func_C1
component "函数C2\n(POST请求)" as Func_C2
component "函数D1\n(消费消息)" as Func_D1

' 数据类型（工件表示生成的数据）
artifact "用户基本信息\n(id, name, email)" as Data_User
artifact "订单统计\n(金额, 数量, 日期)" as Data_Order
artifact "访问日志\n(ip, time, url)" as Data_Log
artifact "产品列表\n(id, name, price)" as Data_Product
artifact "支付结果\n(status, amount, time)" as Data_Payment
artifact "实时事件\n(type, content, timestamp)" as Data_Event

' 数据源与函数的关联（数据源提供函数运行的基础）
DB_A -down-> Func_A1 : 提供数据
DB_A -down-> Func_A2 : 提供数据
Log_File -down-> Func_B1 : 提供数据
API_Service -down-> Func_C1 : 提供接口
API_Service -down-> Func_C2 : 提供接口
Kafka_Queue -down-> Func_D1 : 提供消息

' 函数与数据类型的关联（函数生成对应数据）
Func_A1 -right-> Data_User : 提取
Func_A2 -right-> Data_Order : 提取
Func_B1 -right-> Data_Log : 提取
Func_C1 -right-> Data_Product : 提取
Func_C2 -right-> Data_Payment : 提取
Func_D1 -right-> Data_Event : 提取

' 标题和说明
title 数据源-函数-数据类型关系部署图
note bottom: 说明：节点=数据源，组件=提取函数，工件=数据类型
@enduml

一个复杂点的例子（新代码写法）

点这里查看源码

@startuml 优化JSON结构程序详细流程图

' 定义样式
skinparam backgroundColor white
skinparam handwritten false
skinparam defaultFontName "Microsoft YaHei"

' 主要流程
start
:主程序入口;
note right: __main__

' 定义文件路径
:定义输入输出文件路径;
note right
  input_file
  output_file
  mapping_file
  mapping_output_file
end note

' 调用optimize_json_structure函数
:调用optimize_json_structure();

partition "optimize_json_structure函数" {
  :读取输入JSON文件;
  :调用load_api_mapping();
  
  partition "load_api_mapping函数" {
    :打开mapping文件;
    :提取api_mapping字典;
    :返回api_mapping;
  }
  
  :创建新的数据结构;
  :遍历每个API对象;
  
  while (还有API?) is (是)
    :处理API字段;
    :遍历fields列表;
    
    while (还有field?) is (是)
      :调用process_description();
      
      partition "process_description函数" {
        :处理description字段;
        :分离name和info;
        :保留度量单位;
        :返回处理结果;
      }
      
      :创建新的field字典;
      :添加到optimized_fields;
    endwhile (否)
    
    :更新API的fields;
    :添加到优化后的数据结构;
  endwhile (否)
  
  :保存优化后的JSON;
  :保存API映射关系;
  :返回处理结果;
}

' 验证优化结果
if (优化成功?) then (是)
  :调用verify_optimization();
  
  partition "verify_optimization函数" {
    :读取原始和优化后的文件;
    :加载api_mapping;
    :验证API数量;
    :随机检查API处理结果;
    :验证fields处理;
    :返回验证结果;
  }
  
else (否)
  :输出错误信息;
endif

stop

@enduml

PlantUML文档生成步骤

从这个例子可以看出，生成一个PlantUML文档，主要分为以下几步：
1，@startuml开头，@enduml结尾，再设置标题、页眉、页脚，如：title 时序图
2，设置全图左右模式： top to bottom direction (by default)，或 left to right direction
3，skinparam 定义样式，如：skinparam monochrome false，或!theme bluegray
4，定义数据（class, package, node, folder等）及其中的内容/颜色，如：node "数据库A\n(PostgreSQL)" as DB_A
5，使用箭头定义数据间的关联，如：DB_A -down-> Func_A1 : 提供数据
6，设置分支（Branches）在PlantUML里，我们可以使用 if/then/else 关键词来定义分支。
7, 定义标注/参数流向，note开头，end note结尾。

添加注释

note left of，note right of或note over

箭头注向

箭头为表达函数之间的关系，数据之间的流向，参数间的关系等。
创建一个水平箭头，也可以通过下面的方式来改变箭头 的方向：

-down-> 向下（这个是默认的，等同于 =–>=）
-right-> 向右
-left-> 向左
-up-> 向上
在描述箭头时， up|down|left|right 这几个单词的写法可以简化， 用单词开头的一个或两个字母来替换就行了，比如 -down-> 也可以写成 -d-> 或者 -do-> 。

@startuml
  (*) --> "1"
  -right-> "2"
  -down-> "3"
  -left-> "4"
  -le-> "5"
  -up-> "6"
  -l-> "7"
  -do-> "8"
  -d-> "9"
  -> "10"
  --> (*)
@enduml

我们可以通过，修改箭头样式，来表达不一样的意思：

• 表示一条丢失的消息：末尾加 x
• 让箭头只有上半部分或者下半部分：将<和>替换成\或者 /
• 细箭头：将箭头标记写两次 (如 >> 或 //)
• 虚线箭头：用 – 替代 -
• 箭头末尾加圈：->o
• 双向箭头：<->
  

使用html

<b> 或者 `**`括起来： 加粗文本
<u> 或者 `_ _`括起来：加下划线
<i> 或者 `//`括起来：斜体
<s> 或者 `--`括起来：删除线
<w> 或者 `~~`括起来：波浪线
<color:#AAAAAA> 或 <color:colorName> 用来设置文本颜色
<back:#AAAAAA> 或 <back:colorName> 用来设置背景色
<size:nn> 设置字体大小
<img src="file"> 或 <img:file> 用来添加图片，图片文件必须 是可以访问得到才行。
<img src="http://url"> 或 <img:http://url> 用来添加一个互 联网图片，同样的图片地址必须是可用的才行。

设置BOX

可以使用box和end box画一个盒子将participant包裹起来, 别的组件，如node，class等不适用。
还可以在box关键字之后添加标题或者背景颜色。

查看可用的图式组件

@startuml
listsprite
@enduml

根据这些可用的组件来组合图式。

带标注的箭头（Label on arrows）
缺省情况下，活动图的箭头是没有标注的。但我们可以通过方括号 [labels] 来设置标注，只要把它放在箭头定义的后面就可以了。

复杂图式

http://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000
http://archive.3zso.com/archives/plantuml-quickstart.html#sec-2

可选themes:https://the-lum.github.io/puml-themes-gallery/themes/index.html

@startuml
skin rose
start
partition "**新产品意向与识别**" {
    note
        这是我的注释
        ----
        //Creole 测试//
    end note
    :Ready;
    :HelloWorld(i)>
    :Hello-Sent;
}

@enduml

简介

官方主页：https://plantuml.com/zh/
使用手册：https://plantuml.com/en/guide
TIPS:在 Windows 版本的 VS Code 中，通过 Ctrl + Shift + P 打开命令面板，输入 PlantUML，找到 Preview Current Diagram 命令，或者通过 快捷键 Alt + D，打开预览页面。

PlantUML是一个开源项目，支持快速绘制：

时序图

用例图

类图

对象图

活动图 (旧版语法在此处)

组件图

部署图

状态图

定时图

同时还支持以下非UML图：

JSON 数据

YAML 数据

网络图 (nwdiag)

线框图形界面

架构图

规范和描述语言 (SDL)

Ditaa 图

甘特图

思维导图

工作分解图

实体关系图

通过简单直观的语言来定义这些示意图（语言参考指南）。

学习使用

使用 Sublime + PlantUML 高效地画图

https://www.jianshu.com/p/e92a52770832
https://github.com/jvantuyl/sublime_diagram_plugin
https://www.oracle.com/java/technologies/javase-jdk16-downloads.html
http://archive.3zso.com/archives/plantuml-quickstart.html#sec-5-1

在线编辑器 + VS CODE使用

在线编辑器：http://www.plantuml.com/plantuml
在VS CODE中如何使用：https://blog.csdn.net/stone0823/article/details/100058365
https://blog.csdn.net/daocaoren94/article/details/106339799?utm_medium=distribute.pc_relevant.none-task-blog-2~default~BlogCommendFromBaidu~default-7.control&depth_1-utm_source=distribute.pc_relevant.none-task-blog-2~default~BlogCommendFromBaidu~default-7.control

在 VS Code中安装Markdown Preview Enhanced插件后，在Mrakdown使用PlantUML语法画相关UML图的不显示的问题

利用Markdown Preview Enhanced使用PlantUML语法：
1、PlantUML的图形预览依赖于Graphviz软件。Windows版下载
2、配置环境变量
安装好Graphviz后（比如我安装在：D:\Software\Graphviz），添加环境变量：
变量名：GRAPHVIZ_DOT
变量值：D:\Software\Graphviz\bin\dot.exe
注：变量值是根据我的安装目录配置的。
这样，在使用PlantUML语法是就不会图形显示不出来

其它教学

http://archive.3zso.com/archives/plantuml-quickstart.html#sec-5-1
https://www.jianshu.com/p/e92a52770832
https://plantuml.com/zh/sequence-diagram