GitLab 之 PlantUML 的配置及使用

转载自：https://cloud.tencent.com/developer/article/1010617

1、PlantUML介绍

UML 统一建模语言是一个通用的可视化建模语言，用于对软件进行描述、可视化处理、构造和建立软件系统制品的文档。PlantUML 是一个开源项目，支持快速绘制时序图、流程图、活动图、状态图、用例图、类图等等，开发人员通过简单直观的语言来定义这些示意图。以前我们要绘制以上各图时，一般我们使用可视化工具 visio , rose 等工具，会经常为了布局文字排版，搞的焦头烂额，有了 PlantUML 一切问题都迎刃而解，我们只需要用文字表达出要绘制的图的内容，然后直接生成图片。

2、环境、软件准备

本次演示环境，我是在虚拟机Linux Centos7上操作，以下是安装的软件及版本：

1. Docker：version 1.12.6
2. Git：version 2.10.1
3. GitLab： GitLab Community Edition 9.1.4
4. PlantUML Server：v2017.11

注意：GitLab 对 PlantUML 的支持版本必须 >= 8.16，PlantUML Server 安装这里我们选择 Docker 安装，这里 GitLab、Git、Docker 的安装忽略，着重讲一下如何在 GitLab 上使用 PlantUML 绘制各种图。

3、PlantUML Server 安装及 GitLab 配置

安装要求：

1. jre / jdk 版本 >= 1.6
2. 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 上安装插件体验尝试吧。

参考资料

1. GitLab PlantUML Config
2. PlantUML Server Github
3. PlantUML 官网
4. PlantUML Guide PDF