GitLab 之 PlantUML 的配置及使用

目录

• PlantUML介绍
• 环境、软件准备
• PlantUML Server 安装及 GitLab 配置
• 实例 Demo
  
  • 时序图
  • 流程图
  • 活动图
  • 状态图
  • 用例图
  • 类图
  • 其他图

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@startumlTomcat -> GitLab: Hello, my name is TomcatGitLab -> Tomcat: Hello, my name is GitLab@enduml ```

说明：这是一个最简单的示例，PlantUML 代码段使用 “`plantuml 作为闭合表示为 PlantUML 代码段，@startuml 和 @enduml 为标准的 PlantUML 语法开始、结束标记，但是在 GiltLab 中该标记可以不写，也是可以识别的，在其他工具里面写最好带上吧。

4.1 时序图

4.1.1 时序图-基本-1

```plantuml@startumltitle 时序图-基本-1Tomcat -> GitLab: Hello, my name is TomcatGitLab -> Tomcat: Hello, my name is GitLabTomcat -> GitLab: Nice to meet you.Tomcat <-- GitLab: Nice to meet you too.@enduml ```

4.1.2 时序图-扩展-2

```plantuml@startumltitle 时序图-扩展-2actor 用户participant 参与者1 #yellowparticipant "我的名字有点长\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@startumltitle 时序图-扩展-3actor 用户 #redparticipant 参与者1 #yellowparticipant 参与者2 #yellowparticipant "我的名字有点长\n参与者3" as p3 #99FF99autonumber用户 -> 参与者1: This is message1note left: This is left node message 参与者1 --> 参与者2: This is message2... Please wait 5s ...参与者2 --> 参与者1: This is message3note 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 message10note left of 用户This is <color #118888>HTML</color> noteThis is **bold**This is //italics//This is ""monospaced""This is --stroked --This is __underlined__This is ~~waved~~endnote用户 <<-- p3: This is message11note right of p3 #aquathis is right note of p3endnotenote 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 message20hnote over 用户: This is hnote message参与者1 -> 用户: This is message30rnote over 参与者1This is rnote message_1This is rnote message_2endrnote== This is stage 3 ==autonumberparticipant "参与者4" as p4ref over 用户: This is ref message用户 -> p3: This is message1activate p3p3 -> p4: This is activate messageactivate p4||50||ref over p4: This is ref message p4p4 --> p3: This is deactivate messagedeactivate p4p3 --> 用户: This is message4deactivate p3@enduml ```

4.2 流程图

4.2.1 流程图-基本-1

```plantuml@startumltitle 流程图-基本-1start:Hello world;:This is GitLab **PlantUML Activity** Demo;end@enduml ```

4.2.2 流程图-扩展-2

```plantuml@startumltitle 流程图-扩展-2start:Param;-> This is arrows message;floating note left: This is floating note leftif (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/    endifelse (no)    :Do something for no A;    floating note right: This is floating note rightendifwhile (condition D?):Do something E}:Do something F]endwhileend@enduml ```

4.2.3 流程图-扩展-3

```plantuml@startumltitle 流程图-扩展-3start:Param;-> This is arrows message;note leftThis is note left with <color #FF0000>HTML</color>This is Param noteend noteif (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    endifelse (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 noteendif#AAAAAA:Do something D;repeat#Green:Do something E;repeat while (condition F?)stop@enduml ```

4.3 活动图

4.3.1 活动图-基本-1

```plantuml@startumltitle 活动图-基本-1interface "Interface one" as i1() "interface two" as i2interface "Interface three" as i3i1 - [Component][Component] ..> i2[Component] -> i3@enduml ```

4.3.2 活动图-扩展-2

```plantuml@startumltitle 活动图-扩展-2skinparam componentStyle uml2[Component one] as c1component [Component two] as c2component "This name is too lang\nComponent three" as c3 #greeninterface "Interface one" as i1 () "interface two" as i2 #AAAAAAi1 - c1c1 -> c2c2 -right-> c3c2 ..> i2: Component to Interfacec3 -up-> up: This is upc3 -right-> rightnote top of c2: This is note top messagenote bottom of c1: This is note bottom messagenote left of i1This 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~~endnotenote right of i2This is note right messageBut it is too langendnote@enduml ```

4.3.3 活动图-扩展-3

```plantuml@startumltitle 活动图-扩展-3package "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@startumltitle 状态图-基本-1[*] --> State1State1: This is state messageState1: But it is too langState1 -> State2State2 --> [*]@enduml ```

4.4.2 状态图-扩展-2

```plantuml@startumltitle 状态图-扩展-2scale 350 width[*] --> State1state 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@startumltitle 状态图-扩展-3state "This is State2 name\nBut it is too lang" as State2State2: This is State2 message[*] --> State1State1 --> State2: SuccessedState1 --> [*]: FailedState2 --> State3: SuccessedState2 --> [*]: Failedstate 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: FailedState3 --> [*]: SuccessedState3 --> [*]: Failednote right of State1: This is note rightnote left of State3This 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@startumltitle 用例图-基本-1actor Useractor :I am administrator: as Adminusecase CaseUser --> CaseAdmin --> Case@enduml ```

4.5.2 用例图-扩展-2

```plantuml@startumltitle 用例图-扩展-2actor Useractor :I am administrator: as Adminusecase Case1 as "This is usecase messageBut it is too lang--This is -- message==This is == message..introduction..This is .. message"User -> (Start)User --> Case1 : I am UserAdmin ---> Case1 : I am administratornote right of AdminThis 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~~endnotenote bottom of Case1: This is note bottomnote "This is note message" as n(Start) .. nn .. Case1@enduml  ```

4.5.3 用例图-扩展-3

```plantuml@startumltitle 用例图-扩展-3left to right directionskinparam packageStyle rectangleactor 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@startumltitle 类图-基本-1Class1 --|> Class2Class1 -- Class3Class3 *-- Class4Class3 -o Class5Class5 ..|> Class6Class5 -> Class7Class7 <.. Class8Class7 -x Class9Class9 --+ Class10Class9 -# Class11Class11 <--* Class10@enduml ```

4.6.2 类图-扩展-2

```plantuml@startumltitle 类图-扩展-2Class1 "extends" <|-- Class2: Class2 to Class1Class1 *-- "Composie" Class3Class3 <|-- Class4: extendsUser -o Class2: User to Class2Class1 : -Field1Class1 : #Field2Class1 : ~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 leftnote top of User #redThis is note top of UserBut it is too langendnotenote right of Class3This 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~~endnotenote "This is note message" as nClass3 .. nn ..Class4@enduml ```

4.6.3 类图-扩展-3

```plantuml@startumltitle 类图-扩展-3abstract class AbstractListabstract AbstractCollectioninterface Listinterface CollectionList <|-- AbstractList Collection <|-- AbstractCollectionCollection <|- ListAbstractCollection <|-- AbstractListpackage 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.ArrayListnamespace 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

```plantumltitle 其他图-基本组件-1@startsalt{    [确认按钮]    () 单选按钮(未选中)    (X) 单选按钮(选中)    [] 复选框(未选中)    [X] 复选框(选中)    "请输入电子邮件"    ^请选择下拉列表^}@endsalt ```

4.7.2 其他图-表格-2

```plantumltitle 其他图-表格-2@startsalt{+    用户名: | "请输入用户名/邮箱"    密  码: | "请输入密码"    [  确认  ] | [  取消  ]}@endsalt ```

4.7.3 其他图-表格-3

```plantumltitle 其他图-表格-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

```plantumltitle 其他图-选项卡-4@startsalt{+    {/ <b>Tab1  |  Tab2  |  Tab3  |  Tab4 }    {        用户名: | "请输入用户名"        性  别: | { (X) 男 | () 女 }        爱  好: | { [X]唱歌 | []游泳 | [X]篮球 | []自行车 | []其他 }        图  像: | { "            " | [ 上传 ] }        地  址: | "            "        [  确认  ] | [  取消  ]    }}@endsalt ```

4.7.5 其他图-菜单-5

```plantumltitle 其他图-菜单-5@startsalt{+    {* 文件 | 查找 | 视图 | 窗口 | 工具 | 帮助    文件 | 新建 | 打开文件 | 打开文件夹 | - | 保存 | 打印 | 退出}    {/ <b>Tab1  |  Tab2  |  Tab3  |  Tab4 }    {        用户名: | "请输入用户名"        性  别: | { (X) 男 | () 女 }        爱  好: | { [X]唱歌 | []游泳 | [X]篮球 | []自行车 | []其他 }        图  像: | { "            " | [ 上传 ] }        地  址: | "            "        [  确认  ] | [  取消  ]    }}@endsalt ```

4.7.6 其他图-折叠树-6

```plantumltitle 其他图-折叠树-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