PlantUML 快速入门（一）绘制 UML 类图

阳光穿透心脏的1/2处 2022-09-14 11:07 2070阅读 0赞

大家平日在写技术文档时，往往都有画 UML 图的需要，很多人使用 **PrecessOn** 或者 **darw.io** 等来绘制 UML ，勉强可用但是不够专业。这里为大家推荐一个专门画UML的工具: **PlantUML**

# 1. PlantUML #

--------------------

PlantUML 诞生于 2009 年，知道的人多但是使用的人少。因为它使用特殊的 DSL 进行画图，相较与其他工具，PlantUML 的图不是“画”出来的而是“写”出来的。

虽然有一定学习成本，但是却可以画出更专业的UML图，而且文本格式也便于保存。本文总结 PlantUML 的基本用法，帮助大家快速入门。

## 安装环境 ##

PlantUML 是一个 java 程序，所以有 JDK 就能跑。可以从官网直接下载 jar 文件执行，当然它也提供了 IDEA 和 VSCode 的插件。

需要注意的是，PlantUML 的本地渲染依赖 Graphviz ，需要提前安装并配置环境变量。如果你使用 VSCode 插件，也可以借助云端渲染，只需要作如下配置：

![f4127a7c86dac32c6451001f0bcf865f.png][]

之后就可以在 VSCode 中一边“写” UML 一边预览了。

![5f8717418760920f4f65ce0d4770f640.png][]

接下来我们学习如何写出漂亮的 UML ，像学习其他语言一样 从 `Hello World` 开始。

# 2. Hello World #

--------------------

//hello.pu
    @startuml
    Hello <|-- World
    @enduml

![475e7e23de3d6f68e7950b6311659cdc.png][]

PlantUML 文件通常以 `.pu` 为后缀，

命令行指定 `pu`，

java -jar plantuml.jar hello.pu

在当前目录下会将 `@startuml` 与 `@enduml` 之间的部分生成生成同名的 png

除了`.pu`以外，各种源码文件中的 `@startuml` 与 `@enduml` 也能识别并生成 png，  
例如 `.c`，`.c++`, `.htm`, `.java` 等等，因此我们可以将源码配套的 UML 写入到注释中：

/** * @startuml * class JavaSource { * - String message * } * @enduml */
    public class JavaSource { }

需要注意，一组`@startuml/@enduml` 对应一张 png，如果一个文件中有多组，则生成的 png 文件名会添加自增数字后缀。 此外也可以紧跟在 `@startuml` 之后指定文件名

@startuml foo
    class Foo
    @enduml
    
    @startuml bar
    class Bar
    @enduml
    
    @startuml baz
    class Baz
    @enduml

# 3. 基本语法 #

--------------------

## 注释 ##

单引号后面跟随的内容是注释

@startuml no-scale
    ' 这是注释
    Hello <|-- World
    @enduml

## Title ##

`title`后跟标题

@startuml
    title Hello Title
    Hello <|-- World
    @enduml

![2afc7de3083ec7406f4a6e37ef957c91.png][]

### 多行 title ###

`title` 与 `end title` 之间的输入可以换行

@startuml
    title
    Hello
    Title
    end title
    Hello <|-- World
    @enduml

![482b9cdf1030626b7980d847c38201b1.png][]

### 标题样式 ###

PlantUML 支持使用 **Creole** 这种标记语言，来丰富文字样式，Creole 的用法类似 markdown。

> 参考 ：https://en.wikipedia.org/wiki/Creole\_%28markup%29

@startuml
    title
    * __Hello__
    * **World**
    end title
    Hello <|-- World
    @enduml

![8d6901bde396c6b54eb80d8aaf721bd4.png][]

## 图注 ##

`caption`之后跟的内容显示为图注

@startuml
    caption 图１
    Hello <|-- World
    @enduml

![fd4ea71e55f068193f829dfc99e4f802.png][]

## header/footer ##

@startuml
    header Hello
    Hello <|-- World
    footer World
    @enduml

![5bf9dfc0ea9f7666a39cbea9a3409b97.png][]

`header` `footer`可以在头部和尾部追加注释。 默认 `header` 右对齐， `footer` 居中对齐。

### 对齐方式 ###

@startuml
    left header Hello
    Hello <|-- World
    right footer World
    @enduml

![eee6f0963f7f15acb5448874f3aae080.png][]

在 `header` `footer` 前加 `left` `center` `right` 可以设置对齐方式

### 多行 header/footer ###

跟 `title` 一样, `header ... end header` , `footer ... end footer`

@startuml
    header
    Hello
    Header
    end header
    
    Hello <|-- World
    
    footer
    World
    Footer
    end footer
    @enduml

![40d1587120d78f77f694e2ea3e62299e.png][]

## 放大率 ##

@startuml no-scale
    Hello <|-- World
    @enduml
    
    @startuml scale-1.5
    scale 1.5
    Hello <|-- World
    @enduml
    
    @startuml scale-0.5
    scale 0.5
    Hello <|-- World
    @enduml

![6301238409361798f35be4d127e470fa.png][]

`scale` 可以为UML设置防大率

# 4. 类图 #

--------------------

## Class ##

@startuml
    class Hello
    class World
    @enduml

![4632a9578abb8bcd49512237ba95b789.png][]

`class` 指定类

## Interface ##

@startuml
    interface Hello
    interface World
    @enduml

![4556af353b8a6039891e14837be6e112.png][]

`interface` 指定接口

## 抽象类 ##

@startuml
    abstract class Hello
    @enduml

![db58da5d6894949c832daec6ce294a3b.png][]

`abstract class` 指定抽象类

## 枚举 ##

@startuml
    enum HelloWorld {
        ONE
        TWO
        THREE
    }
    @enduml

![6cd4f38a040ec4feee57795913a04257.png][]

`enum` 指定枚举， `{ ... }` 定义枚举值

## 类型关系 ##

UML中类型之间有六大关系：

*  泛化（Generalization）
 *  实现（Realization）
 *  关联（Association)
 *  聚合（Aggregation）
 *  组合(Composition)
 *  依赖(Dependency)

接下来逐一说明：

### 泛化 ###

泛化关系就是类的继承，java 中对应 `extends` 关键字。

@startuml
    Child --|> Parent
    Parent2 <|-- Child2
    @enduml

![174af0de5941955f988c085e1c7a713d.png][]

`<|--` `--|>` 指定继承关系

### 实现 ###

实现关系，对应 `implements` 关键字

@startuml
    Plane ..|> Flyable
    Flyable <|.. Plane
    @enduml

![86e7df40ccbc76d17603b4e450ef1687.png][]

`..|>`, `<|..` ， 圆点表示虚线

### 依赖 ###

依赖表示使用关系，java中, 被依赖的对象/类, 以方法参数, 局部变量和静态方法调用的形式出现。比如, 厨师在烹饪的时候看了一眼菜谱, 厨师"使用"了菜谱, 照着它炒完菜后，这种使用关系就结束了(临时性).

@startuml
    Chef ..> Recipe
    @enduml

![81ffcf7c88d4f12a2fe581adcecd5704.png][]

### 关联 ###

关联关系，表示"拥有"。 相比依赖关系的临时性和单向性，关联关系具有长期性、平等性(可双向)，所以关联表示的关系比依赖更强。比如现实生活中的夫妻, 师生等关系。长期存在并且是相互的关系。 此外关联可以表示一对一，一对多，多对一，多对多等各种关系。

@startuml
    Address <-- Husband
    Husband <--> Wife
    Husband2 -- Wife2
    @enduml

![ccf9524b9b7ae674c534a3d1a6972a4d.png][]

因为比依赖关系更强, 所以是实线+箭头。 双向关联可以省略箭头。

后面两种关系 “聚合” 和 “组合”，都属于关联关系， 用来表示关联关系中整体与部分的关系。java 中 一个 Class 与其成员变量 Class 类型之间就是这种整体与部分的关联关系。

### 聚合 ###

聚合关系相对于组合弱一些，整体与部分是可分离的。 比如部门与员工，部门有许多员工，员工离职了部门仍然存在，不受影响。反之部门解散了，员工可以去其他部门(整体与部分可分离)

@startuml
    Department o-- Employee
    @enduml

![c8720973ab99fd4098c60029a6849096.png][]

`o` 表示空心菱形

### 组合 ###

组合关系中，整体与部分是不可分离的，整体与部分的生命周期保持一致，少了对方自己的存在无意义。例如人体是有四肢组成的，四肢不能脱离人体存在，人体少了四肢也难言完整

@startuml
    Body "1" *-- "2" Arm
    Body "1" *-- "2" Leg
    @enduml

![8a4b40a1f35ed155239acd2b62e27427.png][]

`*` 表示实心菱形

同时也看到了一对多时的数字表示方法，双引号`"` 包裹，放在线段与Class之间。 多对多也同样。

最后再总结一下六大关系

<table> 
 <thead> 
  <tr> 
   <th></th> 
   <th>继承</th> 
   <th>实现</th> 
   <th>依赖</th> 
   <th>关联</th> 
   <th>聚合</th> 
   <th>组合</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><strong>关系含义</strong></td> 
   <td>功能扩展</td> 
   <td>功能实现</td> 
   <td>使用</td> 
   <td>拥有</td> 
   <td>整体-部分（has-a）</td> 
   <td>整体-部分（contains-a）</td> 
  </tr> 
  <tr> 
   <td><strong>关系特性</strong></td> 
   <td>-</td> 
   <td>-</td> 
   <td>临时性，单向性</td> 
   <td>长期性，可双向（平等性）</td> 
   <td>整体与部分可分离</td> 
   <td>整体与部分不可分离，生命周期一致</td> 
  </tr> 
  <tr> 
   <td><strong>java语法</strong></td> 
   <td>extends</td> 
   <td>implements</td> 
   <td>方法参数，局部变量，静态方法调用</td> 
   <td>成员变量</td> 
   <td>成员变量</td> 
   <td>成员变量</td> 
  </tr> 
  <tr> 
   <td><strong>关系强弱</strong></td> 
   <td>强</td> 
   <td>强</td> 
   <td>弱</td> 
   <td>较强</td> 
   <td>较强</td> 
   <td>非常强</td> 
  </tr> 
  <tr> 
   <td><strong>现实事例</strong></td> 
   <td>父子</td> 
   <td>飞机/鸟可以飞</td> 
   <td>厨师使用菜谱</td> 
   <td>夫妻，师生</td> 
   <td>部门-员工</td> 
   <td>人体-四肢</td> 
  </tr> 
  <tr> 
   <td><strong>图形指向</strong></td> 
   <td>箭头指向父类</td> 
   <td>箭头指向接口</td> 
   <td>箭头指向被使用者</td> 
   <td>指向被拥有者，可双向</td> 
   <td>箭头指向部分， 菱形指向整体</td> 
   <td>箭头指向部分，菱形指向整体</td> 
  </tr> 
 </tbody> 
</table>

## 综合运用 ##

@startuml
    interface One
    interface Two
    interface Three extends Two
    interface Four
    class Five implements One, Three
    class Six extends Five implements Four {
        field: String
        method(): void
    }
    @enduml

![d9107951e56ae532a7a803492ef94816.png][]

## 成员变量、成员方法 ##

@startuml
    class Hello {
        one: String
        three(param1: String, param2: int): boolean
        String two
        int four(List<String> param)
    }
    @enduml

![a46a01453b2ee8224eaaac0db0b3dcb3.png][]

`class`定义后跟大括号，声明成员，然后按照 `变量名：类型` 的顺序声明，类型后置。方法和成员的顺序上可以混在一起，最终成图是，会自动分为两组

### 成员可见性 ###

UML 使用以下符号表示可见性

<table> 
 <thead> 
  <tr> 
   <th>Character</th> 
   <th>Visibility</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>-</code></td> 
   <td><code>private</code></td> 
  </tr> 
  <tr> 
   <td><code>#</code></td> 
   <td><code>protected</code></td> 
  </tr> 
  <tr> 
   <td><code>~</code></td> 
   <td><code>package private</code></td> 
  </tr> 
  <tr> 
   <td><code>+</code></td> 
   <td><code>public</code></td> 
  </tr> 
 </tbody> 
</table>

但是 PlantUML 将这种文字符合进一步图形化：

@startuml
    class Hello {
        - privateField: int
        # protectedField: int
        ~ packagePrivateField: int
        + publicField: int
    
        - privateMethod(): void
        # protectedMethod(): void
        ~ packagePrivateMethod(): void
        + publicMethod(): void
    }
    @enduml

![87d7a37295ff0eb2d6eee4c41d64cee9.png][]

当然，也可以关闭这种图形化符合，继续使用文字符号

@startuml
    skinparam classAttributeIconSize 0
    class Hello {
        - privateField: int
        # protectedField: int
        ~ packagePrivateField: int
        + publicField: int
    
        - privateMethod(): void
        # protectedMethod(): void
        ~ packagePrivateMethod(): void
        + publicMethod(): void
    }
    @enduml

![ccaaaad0db71e4dc7c5d4d5612e89eb3.png][]

通过 `skinparam classAttributeIconSize 0` 关闭图形化符号

### 抽象方法 ###

@startuml
    class Hello {
        {abstract} one: int
        {abstract} two(): int
    }
    @enduml

![5e543b661a4244c01fed42cc416a1c32.png][]

成员前面加 `{abstract}` 标记位抽象成员

### 静态方法 ###

@startuml
    class Hello {
        {static} ONE: int
        {static} two(): int
    }
    @enduml

![199e87a169ecb34dae745834b5a2def7.png][]

添加 `{static}` 表示静态方法

## 泛型 ##

@startuml
    class Hello<H>
    class World<W> 
    @enduml

![7f577f0631dea9227ead50ecd15ab644.png][]

类名后跟`<泛型>`

## 包图 ##

@startuml
    package one.two {
        class Hello
    }
    
    package three.four {
        World -- Hello
    }
    @enduml

![b55840e524f448e2ad08b833ecdfbdc5.png][]

`package <name> {...}` 中可以写类 UML 图

### 包图中的声明顺序 ###

@startuml
    package three.four {
        World -- Hello
    }
    
    package one.two {
        class Hello
    }
    @enduml

![c47a3d9d666ffe22a477b7fb313157c7.png][]

包图的顺序很重要，如上图 `one.two` 中的类被 `three.four` 依赖，所以应该写到先面， 以为 `Hello` 会声明在第一个出现的包中。

## 备注（note） ##

@startuml
    class Fizz
    note left: fizz
    
    class Buzz
    note right: buzz
    
    class Foo
    note top: foo
    
    class Bar
    note bottom: bar
    @enduml

![a3986b71a1f4e5d76bef66effcda657c.png][]

使用 `note <top|bottom|left|right>: <备注>` 为 UML 图添加备注， 备注内容可以是 Creole 语法

### 指定目标类 ###

@startuml
    Fizz -- Buzz
    note left of Fizz: fizz
    note right of Buzz: buzz
    @enduml

`note <位置> of <目标>: <备注>`用来为指定目标 Class 生成备注

### 为类关系进行备注 ###

@startuml
    Fizz -- Buzz
    note on link: fizz-buzz
    note left: buzz
    @enduml

![460908e8318d9989ca25e501b8a0e4dd.png][]

`note on link: <备注>` 可以在类图的关系中添加备注

### 给备注加名字 ###

@startuml
    note "Hello World" as n1
    Hello -- n1
    World .. n1
    
    note "Fizz Buzz" as n2
    @enduml

![5a7856e26fa0e0344f78d3bd47f24e46.png][]

`note "<备注>" as <名字>`用来给备注设置名字，有了名字后，可以通过名字将一个备注关联到多个Class

### 多行备注 ###

@startuml
    class Hello
    note left
    Hello
    World
    end note
    
    Fizz -- Buzz
    note on link
    Fizz
    Buzz
    end note
    note left of Fizz
    fizz
    buzz
    end note
    
    note as n1
    Foo
    Bar
    end note
    @enduml

![57a5999a97e83224685e678b7e155ef2.png][]

`end note` 用来结束多行的备注

[f4127a7c86dac32c6451001f0bcf865f.png]: /images/20220828/2be0c07218f740649660539a9a40d77e.png
[5f8717418760920f4f65ce0d4770f640.png]: /images/20220828/f8068abfb5804ea69efffba2d21fdb74.png
[475e7e23de3d6f68e7950b6311659cdc.png]: /images/20220828/b9b4ec6a314545518cc732dd028426fe.png
[2afc7de3083ec7406f4a6e37ef957c91.png]: /images/20220828/d373de2b030141daa31600e23e8fd3e7.png
[482b9cdf1030626b7980d847c38201b1.png]: /images/20220828/805ca8144cf64e64b7c99ee73bfe2d4e.png
[8d6901bde396c6b54eb80d8aaf721bd4.png]: /images/20220828/8baabe62a0d046619e62b132f8ebbe52.png
[fd4ea71e55f068193f829dfc99e4f802.png]: /images/20220828/b5c5a7bebfee4f4e915b90bd166d06fc.png
[5bf9dfc0ea9f7666a39cbea9a3409b97.png]: /images/20220828/4c352c032f9c45e2847f24bdf64d2329.png
[eee6f0963f7f15acb5448874f3aae080.png]: /images/20220828/30e66f0bc747468b9c87a8554ded1ac0.png
[40d1587120d78f77f694e2ea3e62299e.png]: /images/20220828/849806bae0e84f7ea4c13fefa7e014b0.png
[6301238409361798f35be4d127e470fa.png]: /images/20220828/2bab7ec90e9a42fe82f858a0c0714f76.png
[4632a9578abb8bcd49512237ba95b789.png]: /images/20220828/a1f97df5aec04ad99aca2f05562fd521.png
[4556af353b8a6039891e14837be6e112.png]: /images/20220828/cbbd2de376164b4ba683eb8cba4c3b70.png
[db58da5d6894949c832daec6ce294a3b.png]: /images/20220828/4603fa4cfa8a47768d076adb41788672.png
[6cd4f38a040ec4feee57795913a04257.png]: /images/20220828/67410ce4ba434c6db5fbb52f0ee3fe9b.png
[174af0de5941955f988c085e1c7a713d.png]: /images/20220828/9f08a49c6b1e421383924b15048eaaea.png
[86e7df40ccbc76d17603b4e450ef1687.png]: /images/20220828/04a5066a057e4d3eb9e3a242afb76040.png
[81ffcf7c88d4f12a2fe581adcecd5704.png]: /images/20220828/47c1f5ff93c149de91d76a24a94af7a9.png
[ccf9524b9b7ae674c534a3d1a6972a4d.png]: /images/20220828/cccb61f016a84cd6ae9e267a938bc555.png
[c8720973ab99fd4098c60029a6849096.png]: /images/20220828/89c3b94ccdd74331bb5ae76a0c8f2550.png
[8a4b40a1f35ed155239acd2b62e27427.png]: /images/20220828/033c961a68234959832e1175d37def65.png
[d9107951e56ae532a7a803492ef94816.png]: /images/20220828/4dc6d6956b3e40b68074d1f3a2843eb6.png
[a46a01453b2ee8224eaaac0db0b3dcb3.png]: /images/20220828/3b7088761b44487caa49590d9c286513.png
[87d7a37295ff0eb2d6eee4c41d64cee9.png]: /images/20220828/1459ab26f50c41958f58deae43c14b66.png
[ccaaaad0db71e4dc7c5d4d5612e89eb3.png]: /images/20220828/7eba7102367342419e5d6ff2a09ea554.png
[5e543b661a4244c01fed42cc416a1c32.png]: /images/20220828/978541aada31446a8f0651ad13378152.png
[199e87a169ecb34dae745834b5a2def7.png]: /images/20220828/c6c13221d79149bb83893d8292923317.png
[7f577f0631dea9227ead50ecd15ab644.png]: /images/20220828/683b46e941aa4e3f915b8384aba152d2.png
[b55840e524f448e2ad08b833ecdfbdc5.png]: /images/20220828/7ece747dd3224a18801a48d4b6ff79c3.png
[c47a3d9d666ffe22a477b7fb313157c7.png]: /images/20220828/f6b6ef35a56945858f553f1d3aa0274f.png
[a3986b71a1f4e5d76bef66effcda657c.png]: /images/20220828/7c8189ae66354416b12b1f449f3d2b98.png
[460908e8318d9989ca25e501b8a0e4dd.png]: /images/20220828/64d34006b7cd4bcaa326cb51f6d6e156.png
[5a7856e26fa0e0344f78d3bd47f24e46.png]: /images/20220828/8ebfd1650a5646a186c3b79c69ad5968.png
[57a5999a97e83224685e678b7e155ef2.png]: /images/20220828/f93f193d3c8a46ad9d384ad3a1dc5304.png