GitLab 之 PlantUML 的配置及使用
转载自：https://cloud.tencent.com/developer/article/1010617
1、PlantUML介绍
UML 统一建模语言是一个通用的可视化建模语言，用于对软件进行描述、可视化处理、构造和建立软件系统制品的文档。PlantUML 是一个开源项目，支持快速绘制时序图、流程图、活动图、状态图、用例图、类图等等，开发人员通过简单直观的语言来定义这些示意图。以前我们要绘制以上各图时，一般我们使用可视化工具 visio , rose 等工具，会经常为了布局文字排版，搞的焦头烂额，有了 PlantUML 一切问题都迎刃而解，我们只需要用文字表达出要绘制的图的内容，然后直接生成图片。
2、环境、软件准备
本次演示环境，我是在虚拟机Linux Centos7上操作，以下是安装的软件及版本：
- Docker：version 1.12.6
- Git：version 2.10.1
- GitLab： GitLab Community Edition 9.1.4
- PlantUML Server：v2017.11
注意：GitLab 对 PlantUML 的支持版本必须 >= 8.16，PlantUML Server 安装这里我们选择 Docker 安装，这里 GitLab、Git、Docker 的安装忽略，着重讲一下如何在 GitLab 上使用 PlantUML 绘制各种图。
3、PlantUML Server 安装及 GitLab 配置
安装要求：
- jre / jdk 版本 >= 1.6
- maven 版本 >= 3.0.2
启动 PlantUML Server 服务，这里有三种方式启动服务：
1、使用 mvn jetty 启动服务
$ sudo yum install graphviz openjdk-7-jdk git-core maven
$ git clone https://github.com/plantuml/plantuml-server.git
$ cd plantuml-server
$ mvn package
$ mvn jetty:run #默认是8080，如果端口已占用，使用 mvn jetty:run -Djetty.port=9999 修改端口
2、使用 docker 启动服务
2.1 使用官方 plantuml/plantuml-server 镜像启动
我们可以选择 jetty 或者 tomcat 容器来启动服务
$ docker run -d -p 8080:8080 plantuml/plantuml-server:jetty
$ docker run -d -p 8080:8080 plantuml/plantuml-server:tomcat
2.2 自己构建 plantuml-server 镜像启动
$ git clone https://github.com/plantuml/plantuml-server.git
$ cd plantuml-server
$ docker image build -t plantuml-server .
$ docker run -d -p 8080:8080 plantuml-server
3、使用 maven + tomcat 手动配置
$ sudo apt-get install graphviz openjdk-7-jdk git-core maven tomcat7
$ git clone https://github.com/plantuml/plantuml-server.git
$ cd plantuml-server
$ mvn package
$ sudo cp target/plantuml.war /var/lib/tomcat7/webapps/plantuml.war
$ sudo chown tomcat7:tomcat7 /var/lib/tomcat7/webapps/plantuml.war
$ sudo service tomcat7 restart
服务启动之后，PlantUML Server 监听http://localhost:8080/plantuml，注意：上边2.1服务启动完成后，监听http://localhost:8080。
启动完成后，需要在 GitLab 上配置开启 PlantUML，管理员登录 -> Admin Area -> Settings，复选框选中 Enable PlantUML，输入 PlantUML URL（就是刚刚启动的 PlantUML Server 服务监听地址）。好了现在可以开始 PlantUML 之旅了。
4、实例 Demo
这里我们使用 Markdown 代码块的方式展示，只需要在 .md 文件中，按照 PlantUML 语法格式输入，在 GitLab上 点击 Preview 即可查看效果，它是以直接生成图片的方式，通过上边 PlantUML Server 服务生成图片，并提供图片访问，非常方便直观。
```plantuml
@startuml
Tomcat -> GitLab: Hello, my name is Tomcat
GitLab -> Tomcat: Hello, my name is GitLab
@enduml
```
说明：这是一个最简单的示例，PlantUML 代码段使用 “`plantuml 作为闭合表示为 PlantUML 代码段，@startuml 和 @enduml 为标准的 PlantUML 语法开始、结束标记，但是在 GiltLab 中该标记可以不写，也是可以识别的，在其他工具里面写最好带上吧。
4.1 时序图
4.1.1 时序图-基本-1
```plantuml
@startuml
title 时序图-基本-1
Tomcat -> GitLab: Hello, my name is Tomcat
GitLab -> Tomcat: Hello, my name is GitLab
Tomcat -> GitLab: Nice to meet you.
Tomcat <-- GitLab: Nice to meet you too.
@enduml
```
4.1.2 时序图-扩展-2
```plantuml
@startuml
title 时序图-扩展-2
actor 用户
participant 参与者1 #yellow
participant "我的名字有点长\n参与者2" as p2
用户 -> 参与者1: http request
参与者1 -> 用户: http response
用户 -> p2: authentication request
用户 <-- p2: authentication response
用户 -> 用户: send message to myself.
@enduml
```
4.1.3 时序图-扩展-3
```plantuml
@startuml
title 时序图-扩展-3
actor 用户 #red
participant 参与者1 #yellow
participant 参与者2 #yellow
participant "我的名字有点长\n参与者3" as p3 #99FF99
autonumber
用户 -> 参与者1: This is message1
note left: This is left node message
参与者1 --> 参与者2: This is message2
... Please wait 5s ...
参与者2 --> 参与者1: This is message3
note right: This is right node message
参与者1 -> 用户: This is message4
用户 -[#0000FF]> 参与者2: This is message5
用户 <-[#0000FF]- 参与者2: This is message6
== This is stage 1 ==
autonumber 10
用户 ->> p3: This is message10
note left of 用户
This is <color #118888>HTML</color> note
This is **bold**
This is //italics//
This is ""monospaced""
This is --stroked --
This is __underlined__
This is ~~waved~~
endnote
用户 <<-- p3: This is message11
note right of p3 #aqua
this is right note of p3
endnote
note over p3: This is note over p3
用户 -> 用户: This is message 12 to myself\n but it is too long.
== This is stage 2 ==
autonumber 20 10
用户 -> 参与者1: This is message20
hnote over 用户: This is hnote message
参与者1 -> 用户: This is message30
rnote over 参与者1
This is rnote message_1
This is rnote message_2
endrnote
== This is stage 3 ==
autonumber
participant "参与者4" as p4
ref over 用户: This is ref message
用户 -> p3: This is message1
activate p3
p3 -> p4: This is activate message
activate p4
||50||
ref over p4: This is ref message p4
p4 --> p3: This is deactivate message
deactivate p4
p3 --> 用户: This is message4
deactivate p3
@enduml
```
4.2 流程图
4.2.1 流程图-基本-1
```plantuml
@startuml
title 流程图-基本-1
start
:Hello world;
:This is GitLab **PlantUML Activity** Demo;
end
@enduml
```
4.2.2 流程图-扩展-2
```plantuml
@startuml
title 流程图-扩展-2
start
:Param;
-> This is arrows message;
floating note left: This is floating note left
if (condition A) then (yes)
:Do something for yes A|
if (condition B) then (yes)
:Do something for yes B>
elseif (condition C) then (yes)
:Do something for yes C<
stop
else (nothing)
:Do something for nothing/
endif
else (no)
:Do something for no A;
floating note right: This is floating note right
endif
while (condition D?)
:Do something E}
:Do something F]
endwhile
end
@enduml
```
4.2.3 流程图-扩展-3
```plantuml
@startuml
title 流程图-扩展-3
start
:Param;
-> This is arrows message;
note left
This is note left with <color #FF0000>HTML</color>
This is Param note
end note
if (condition A) then (true)
-[#black,dashed]->
:Do something for yes A;
if (condition B) then (yes)
-[#000000]->
:Do something for yes B;
else
-[#green,bold]->
if (condition C) then (yes)
:Do something for yes C;
else (no)
:Do something for no C;
endif
endif
else (false)
-[#blue,dotted]->
:Do something for no A;
note right
This is note right with <color #118888>HTML</color>
====
* This is **bold**
* This is //italics//
* This is ""monospaced""
* This is --stroked --
* This is __underlined__
* This is ~~waved~~
end note
endif
#AAAAAA:Do something D;
repeat
#Green:Do something E;
repeat while (condition F?)
stop
@enduml
```
4.3 活动图
4.3.1 活动图-基本-1
```plantuml
@startuml
title 活动图-基本-1
interface "Interface one" as i1
() "interface two" as i2
interface "Interface three" as i3
i1 - [Component]
[Component] ..> i2
[Component] -> i3
@enduml
```
4.3.2 活动图-扩展-2
```plantuml
@startuml
title 活动图-扩展-2
skinparam componentStyle uml2
[Component one] as c1
component [Component two] as c2
component "This name is too lang\nComponent three" as c3 #green
interface "Interface one" as i1
() "interface two" as i2 #AAAAAA
i1 - c1
c1 -> c2
c2 -right-> c3
c2 ..> i2: Component to Interface
c3 -up-> up: This is up
c3 -right-> right
note top of c2: This is note top message
note bottom of c1: This is note bottom message
note left of i1
This is note left message with <color #FF0000>HTML</color>
This is **bold**
This is //italics//
This is ""monospaced""
This is --stroked --
This is __underlined__
This is ~~waved~~
endnote
note right of i2
This is note right message
But it is too lang
endnote
@enduml
```
4.3.3 活动图-扩展-3
```plantuml
@startuml
title 活动图-扩展-3
package "This is package" {
interface - [package 2]
[package 2] -> [package 3]
}
node "This is node" {
[package 3] -- [node 1]
[node 1] --> [node 2]
}
cloud {
[node 2] --> [cloud 1]
[node 2] --> [cloud 2]
[node 2] --> [cloud 3]
}
database "This is Mysql" {
folder "This is folder" {
[folder 1]
[folder 2]
}
frame "This is frame" {
[frame 1]
}
}
[cloud 1] --> [folder 1]
[cloud 1] --> [folder 2]
[cloud 2] --> [folder 1]
[cloud 2] --> [folder 2]
[cloud 3] --> [frame 1]
@enduml
```
4.4 状态图
4.4.1 状态图-基本-1
```plantuml
@startuml
title 状态图-基本-1
[*] --> State1
State1: This is state message
State1: But it is too lang
State1 -> State2
State2 --> [*]
@enduml
```
4.4.2 状态图-扩展-2
```plantuml
@startuml
title 状态图-扩展-2
scale 350 width
[*] --> State1
state State1 {
[*] -> State1.1
State1.1 --> State2: State 1.1 to 2
State2 --> State1.1: State 2 to 1.1
}
state State2 {
[*] --> State2.1
State2.1 --> State2.1.1: State 2.1 to 2.1.1
State2.1.1 --> State2.1: State 2.1.1 to 2.1
state State2.1.1 {
State2.1.1.1 -> State2.1.1.2
}
--
[*] -> State2.2
State2.2 --> State2.2.1: State 2.2 to 2.2.1
State2.2.1 --> State2.2: State 2.2.1 to 2.2
}
@enduml
```
4.4.3 状态图-扩展-3
```plantuml
@startuml
title 状态图-扩展-3
state "This is State2 name\nBut it is too lang" as State2
State2: This is State2 message
[*] --> State1
State1 --> State2: Successed
State1 --> [*]: Failed
State2 --> State3: Successed
State2 --> [*]: Failed
state State3 {
state "This is State3.1 name\nBut it is too lang" as State3.1
State3.1: This is State3.1 message
[*] --> State3.1
State3.1 --> State3.2: State 3.1 to 3.2
State3.2 --> State3.1: State 3.2 to 3.1
State3.1 --> State3.1: Failed
}
State3 --> State3: Failed
State3 --> [*]: Successed
State3 --> [*]: Failed
note right of State1: This is note right
note left of State3
This is note right with <color #FF0000>HTML</color>
This is **bold**
This is //italics//
This is ""monospaced""
This is --stroked --
This is __underlined__
This is ~~waved~~
endnote
@enduml
```
4.5 用例图
4.5.1 用例图-基本-1
```plantuml
@startuml
title 用例图-基本-1
actor User
actor :I am administrator: as Admin
usecase Case
User --> Case
Admin --> Case
@enduml
```
4.5.2 用例图-扩展-2
```plantuml
@startuml
title 用例图-扩展-2
actor User
actor :I am administrator: as Admin
usecase Case1 as "This is usecase message
But it is too lang
--
This is -- message
==
This is == message
..introduction..
This is .. message"
User -> (Start)
User --> Case1 : I am User
Admin ---> Case1 : I am administrator
note right of Admin
This is note right with <color #FF0000>HTML</color>
This is **bold**
This is //italics//
This is ""monospaced""
This is --stroked --
This is __underlined__
This is ~~waved~~
endnote
note bottom of Case1: This is note bottom
note "This is note message" as n
(Start) .. n
n .. Case1
@enduml
```
4.5.3 用例图-扩展-3
```plantuml
@startuml
title 用例图-扩展-3
left to right direction
skinparam packageStyle rectangle
actor User1 <<用户>>
actor User2 <<用户>>
actor :I am administrator: as Admin <<管理员>>
rectangle actions {
User1 -- (Start)
User2 -- (Start)
(Start) --> (action): Begin
(action) .> (action1): Use
(action2) .> (action): Extends
(action) --> (End): End
(End) -- Admin
}
@enduml
```
4.6 类图
4.6.1 类图-基本-1
```plantuml
@startuml
title 类图-基本-1
Class1 --|> Class2
Class1 -- Class3
Class3 *-- Class4
Class3 -o Class5
Class5 ..|> Class6
Class5 -> Class7
Class7 <.. Class8
Class7 -x Class9
Class9 --+ Class10
Class9 -# Class11
Class11 <--* Class10
@enduml
```
4.6.2 类图-扩展-2
```plantuml
@startuml
title 类图-扩展-2
Class1 "extends" <|-- Class2: Class2 to Class1
Class1 *-- "Composie" Class3
Class3 <|-- Class4: extends
User -o Class2: User to Class2
Class1 : -Field1
Class1 : #Field2
Class1 : ~Method1()
Class1 : +Method2()
class Class2 {
int id
String data
int getSize()
void save()
void update()
void delete()
List<String> getList()
}
class Class3 {
This is Class3 message
But it is too lang
..
This Class3 .. message
==
This is Class == message
__
This is Class __ message
--
This is Class -- message
But it it too lang
}
class User {
This is class User
..get method..
+getName()
+getAddress()
..set method..
+setName()
+setAddress()
__private field__
-int age
-String sex
--protect field--
#String phone
--static field--
{static} String id
--abstract method--
{abstract} void methods()
}
note left of Class1: This is note left
note top of User #red
This is note top of User
But it is too lang
endnote
note right of Class3
This is note with <color #118888>HTML</color>
This is **bold**
This is //italics//
This is ""monospaced""
This is --stroked --
This is __underlined__
This is ~~waved~~
endnote
note "This is note message" as n
Class3 .. n
n ..Class4
@enduml
```
4.6.3 类图-扩展-3
```plantuml
@startuml
title 类图-扩展-3
abstract class AbstractList
abstract AbstractCollection
interface List
interface Collection
List <|-- AbstractList
Collection <|-- AbstractCollection
Collection <|- List
AbstractCollection <|-- AbstractList
package java.util {
AbstractList <|-- ArrayList
class ArrayList {
This is package java.util
}
}
namespace net.test {
com.test.ArrayList <|- ArrayList
class ArrayList {
This is namespace net.test
}
}
ArrayList <|-- net.test.ArrayList
namespace com.test {
AbstractList <|-- ArrayList
class ArrayList {
This is namespace com.test
}
}
class ArrayList <? extends Element> {
Object[] elementData
int size()
}
package "enum and annotation" #DDDDDD {
enum HttpMethod {
POST
GET
PUT
DELETE
PATCH
}
annotation Annotation
}
@enduml
```
4.7 其他图
4.7.1 其他图-基本组件-1
```plantuml
title 其他图-基本组件-1
@startsalt
{
[确认按钮]
() 单选按钮(未选中)
(X) 单选按钮(选中)
[] 复选框(未选中)
[X] 复选框(选中)
"请输入电子邮件"
^请选择下拉列表^
}
@endsalt
```
4.7.2 其他图-表格-2
```plantuml
title 其他图-表格-2
@startsalt
{+
用户名: | "请输入用户名/邮箱"
密 码: | "请输入密码"
[ 确认 ] | [ 取消 ]
}
@endsalt
```
4.7.3 其他图-表格-3
```plantuml
title 其他图-表格-3
@startsalt
{#
column1 | column2 | column3 | column4
row1 | value1_2 | value1_3 | value1_4
row2 | value2_2 | value2_3 | value2_4
}
@endsalt
```
4.7.4 其他图-选项卡-4
```plantuml
title 其他图-选项卡-4
@startsalt
{+
{/ <b>Tab1 | Tab2 | Tab3 | Tab4 }
{
用户名: | "请输入用户名"
性 别: | { (X) 男 | () 女 }
爱 好: | { [X]唱歌 | []游泳 | [X]篮球 | []自行车 | []其他 }
图 像: | { " " | [ 上传 ] }
地 址: | " "
[ 确认 ] | [ 取消 ]
}
}
@endsalt
```
4.7.5 其他图-菜单-5
```plantuml
title 其他图-菜单-5
@startsalt
{+
{* 文件 | 查找 | 视图 | 窗口 | 工具 | 帮助
文件 | 新建 | 打开文件 | 打开文件夹 | - | 保存 | 打印 | 退出}
{/ <b>Tab1 | Tab2 | Tab3 | Tab4 }
{
用户名: | "请输入用户名"
性 别: | { (X) 男 | () 女 }
爱 好: | { [X]唱歌 | []游泳 | [X]篮球 | []自行车 | []其他 }
图 像: | { " " | [ 上传 ] }
地 址: | " "
[ 确认 ] | [ 取消 ]
}
}
@endsalt
```
4.7.6 其他图-折叠树-6
```plantuml
title 其他图-折叠树-6
@startsalt
{
{T
+ Folder
++ Folder1
+++ Folder1.1
++++ File1.1.1
++ Folder1.2
+++ File1.2.1
+++ File1.2.2
+++ File1.2.3
++ Folder2
+++ File2.1
+++ Folder2.2
++++ File2.2.1
++ Folder3
}
}
@endsalt
```
好了，PlantUML 还有其他类型的图，这里就不一一举例子了。如果想尝试的话，除了在 GitLab 上，还可以在 Sublime 安装插件，或者是在 Eclipse 上安装插件，再或者是在 IntelliJ IDEA 上安装插件体验尝试吧。
参考资料
