程序员画图的正确姿势 | PlantUML(三)

本文已参与[新人创作礼]活动，一起开启掘金创作之路

1 说明

关于PlantUML的背景知识已经在程序员画图的正确姿势 | PlantUML(一)文章做了说明，这一篇文章主要讲解PlantUML的语法部分。上一篇文章程序员画图的正确姿势 | PlantUML(二)已经对PlantUML的部分语法进行了讲解，这篇文章将会对剩下的图表：状态机图 (State Machine Diagram)、对象图 (Object Diagram)、部署图 (Deployment Diagram)、时序图 (Timing Diagram)、网络图 (Network)、线框图 (Wireframe)、甘特图 (Gantt Diagram)、思维导图 (MindMap)、工作分解结构图 (Work Breakdown Structure)、JSON可视化 (Display JSON Data)、YAML可视化 (Display YAML Data) 画法进行介绍。

2 PlantUML语法

2.1 状态机图 (State Machine Diagram)

状态机图是用来描述基于大卫•哈雷尔（David Harel）的状态图概念的系统行为的一种图表。状态图描绘允许的状态和转换以及影响这些转换的事件，它有助于可视化对象的整个生命周期，从而更好地理解以状态主导 (State-based) 的系统。以前写的关于状态机的两篇文章《什么是状态机？一篇文章就够了》和《介绍一个状态机框架，纯c语言打造(附源码)》可以参考看一下。一般的状态图及其描述语言如下：

@startuml
[*] -> State1
State1 --> State2 : Succeeded
State1 --> [*] : Aborted
State2 --> State3 : Succeeded
State2 --> [*] : Aborted
state State3 {
  state "Accumulate Enough Data\nLong State Name" as long1
  long1 : Just a test
  [*] --> long1
  long1 --> long1 : New Data
  long1 --> ProcessData : Enough Data
}
State3 --> State3 : Failed
State3 --> [*] : Succeeded / Save Result
State3 --> [*] : Aborted
@enduml

• 使用[*]表示开始和结束状态图，使用-->添加箭头；
• 状态也可能是合成的，使用关键字state和花括号{}来定义合成状态；
• 使用关键字state定义长名字状态，后面跟一个as给长名字状态取一个别名。如：state "Accumulate Enough Data\nLong State Name" as long1；
• 状态后面加冒号:可以加上一段对状态的描述文字，如：long1 : Just a test；
• 在状态的转移流程中，在冒号:后可以加上一段转移条件的描述文字，如：long1 --> ProcessData : Enough Data。

2.2 对象图 (Object Diagram)

对象图 是实例 (Instance) 的表达，包括对象和数据值。静态的对象图是类图的一个实例，它是系统在某个时间点的详细状态的快照，不同之处在于类图表示了一个由类及其关系组成的抽象模型，而对象图则表达了特定时刻的实例。对象图的使用是相当有限的，它常被用作展示数据结构例子。一般的对象图及其描述语言如下：

@startuml
object London {
name = "London"
country = "UK"
}

object Washington {
name = "Washington"
country = "USA"
}

object NewYork {
name = "NewYork"
country = "USA"
}

object Berlin {
name = "Berlin"
country = "Germany"
}

map CapitalCity {
 UK *-> London
 USA *--> Washington
 Germany *---> Berlin
}

NewYork --> CapitalCity::USA
@enduml

• 使用关键字object定义实例；
• 对象之间的Extension（扩展）、Composition（组合）、Aggregation（聚合）关系，分别用<|--、*--、o--来进行标记，和类图一样；
• 用花括号{}批量声明属性；

2.3 部署图 (Deployment Diagram)

部署图它是一个结构性图表。部署图对运行时配置进行建模，并可视化应用程序中产出的分布。在大多数情况下，它表达了硬件配置以及和软件组件之间的关系。从中可以了解到软件和硬件组件之间的物理拓扑、连接关系以及处理节点的分布情况。一般的部署图及其描述语言如下：

@startuml

node 客户端 {
    agent agent0[
        <<artifact>>
        KaoQing.exe
    ]
}

node 服务器 {
    agent agent1[
        <<artifact>>
        KpServer.exe
    ]

        agent agent2[
        <<artifact>>
        CradReader.exe
    ]

    agent agent3[
        <<database>>
        KaoQing.exe
    ]
}
node IC卡读卡器 #palegreen;line:green;line.dashed;text:green [
    IC卡读卡器
    {number = 3}
]

服务器 -- 客户端 : {100M以太网}
服务器 --- IC卡读卡器 : {RS-232C}
agent1 ..> agent3
agent1 --> agent2
@enduml

• 部署图支持的元素非常多，如：actor、artifact、cloud、component、node、usecase等等；
• 各个元素之间的链接标记有..，~~ ，==，各自渲染出来的视觉效果都不一样；
• 可以改变元素的视觉样式，如：node IC卡读卡器 #palegreen;line:green;line.dashed;text:green
• 在链接各元素时，可以加上冒号:，在其后面加上链接的说明文字，如：服务器 --- IC卡读卡器 : {RS-232C}。

2.4 时序图 (Timing Diagram)

时序图显示了既定时间内对象的行为。它通过描述对象之间发送消息的时间顺序显示多个对象之间的动态协作。时序图是序列图的一种特殊形式，它俩之间的差异是轴反转，时间从左到右增加，生命线显示在垂直排列的独立隔间中。一般的时序图及其描述语言如下：

@startuml

clock clk with period 1
binary "enable" as en
binary "R/W" as rw
binary "data Valid" as dv
concise "dataBus" as db
concise "address bus" as addr

@6 as :write_beg
@10 as :write_end

@15 as :read_beg
@19 as :read_end

@0
en is low
db is "0x0"
addr is "0x03f"
rw is low
dv is 0

@:write_beg-3
 en is high
@:write_beg-2
 db is "0xDEADBEEF"
@:write_beg-1
dv is 1
@:write_beg
rw is high

@:write_end
rw is low
dv is low
@:write_end+1
rw is low
db is "0x0"
addr is "0x23"

@12
dv is high
@13 
db is "0xFFFF"

@20
en is low
dv is low
@21 
db is "0x0"

highlight :write_beg to :write_end #Gold:Write
highlight :read_beg to :read_end #lightBlue:Read

db@:write_beg-1 <-> @:write_end : setup time
db@:write_beg-1 -> addr@:write_end+1 : hold
@enduml

• 使用concise或者robust关键字声明参与者, 选择哪个取决于所需的显示样式。如：concise "address bus" as addr；
• 时钟信号通过关键字clock来声明，如：clock clk with period 1，声明时钟周期为1；
• 电平信号通过关键字binary来什么，如：binary "R/W" as rw；
• 通过@来标注时间节点，和is动词来定义状态；
• 通过关键字highlight可以将一段时间高亮，如：highlight :write_beg to :write_end #Gold:Write；
• 通过<->和->能够增加标识线，如：db@:write_beg-1 <-> @:write_end : setup time。

2.5 网络图 (Network)

PlantUML采用nwdiag工具来快速绘制网络拓扑图，nwdiag已经被完全集成进PlantUML中。来看一下其具体语法内容。一般的网络图和其标记语法如下：

@startuml
!include <office/Servers/application_server>
!include <office/Servers/database_server>

nwdiag {
  network dmz {
      address = "210.x.x.x/24"

      web01 [address = "210.x.x.1, 210.x.x.20",  description = "<$application_server>\n web01"]
      web02 [address = "210.x.x.2",  description = "<$application_server>\n web02"];
  }
  network internal {
      address = "172.x.x.x/24";

      web01 [address = "172.x.x.1"];
      web02 [address = "172.x.x.2"];
      db01 [address = "172.x.x.100",  description = "<$database_server>\n db01"];
      db02 [address = "172.x.x.101",  description = "<$database_server>\n db02"];
  }
}
@enduml

• 使用关键字network可以定义一个网络元素，如：network dmz、network internal；
• 使用中括号[]可以对网络节点的各个内容进行描述，如：address、description。

2.6 线框图 (Wireframe)

线框图 称为页面示意图或屏幕蓝图，是整个交互式设计过程中的必要步骤，包含了产品的主要功能，页面逻辑、布局，能够引导页面内容及概念。是展示网站或产品框架的视觉指南。通常在项目生命周期的早期阶段进行。一般的线框图及其描述语言如下：

@startuml
salt

{+
{* File | Edit | Source | Refactor
 Refactor | New | Open File | - | Close | Close All }
{/ General | Fullscreen | Behavior | Saving }
{
{ Open image in: | ^Smart Mode^ }
[X] Smooth images when zoomed
[X] Confirm image deletion
[ ] Show hidden images
}
[Close]
}
@enduml

• 一个窗口必须以花括号{}开头和结尾；
• #显示所有垂直水平线；
• !显示所有垂直线；
• -显示所有水平线；
• +显示外框线；
• 使用{*标记一个菜单；
• 使用{/标记一个选项卡；
• 使用[X]标记一个Checked box。

2.7 甘特图 (Gantt Diagram)

甘特图又称为横道图、条状图(Bar chart)。其通过条状图来显示项目、进度和其他时间相关的系统进展的内在关系随着时间进展的情况。以提出者亨利·劳伦斯·甘特（Henry Laurence Gantt） 先生的名字命名。一般甘特图及其描述语言如下所示：

@startuml
<style>
ganttDiagram {
	task {
		FontName Helvetica
		FontColor red
		FontSize 18
		FontStyle bold
		BackGroundColor GreenYellow
		LineColor blue
	}
	milestone {
		FontColor blue
		FontSize 25
		FontStyle italic
		BackGroundColor yellow
		LineColor red
	}
	note {
		FontColor DarkGreen
		FontSize 10
		LineColor OrangeRed
	}
	arrow {
		FontName Helvetica
		FontColor red
		FontSize 18
		FontStyle bold
		BackGroundColor GreenYellow
		LineColor blue
		LineStyle 8.0;13.0
		LineThickness 3.0
	}
	separator {
		BackgroundColor lightGreen
		LineStyle 8.0;3.0
		LineColor red
		LineThickness 1.0
		FontSize 16
		FontStyle bold
		FontColor purple
		Margin 5
		Padding 20
	}
	timeline {
	    BackgroundColor Bisque
	}
	closed {
		BackgroundColor pink
		FontColor red
	}
}
</style>
Project starts the 2020-12-01

[Task1] lasts 10 days
sunday are closed

note bottom
  memo1 ...
  memo2 ...
  explanations1 ...
  explanations2 ...
end note

[Task2] lasts 20 days
[Task2] starts 10 days after [Task1]'s end
-- Separator title --
[M1] happens on 5 days after [Task1]'s end

<style>
	separator {
	    LineColor black
		Margin 0
		Padding 0
	}
</style>

-- end --
@enduml

• 甘特图是用自然语言描述的，使用非常简单的句子（主语-动词-补语）；
• 通过关键字last来定义时长，如，[Task1] lasts 10 days；
• 通过关键字start来定义开始，如，[Task2] lasts 20 days；
• 通过关键字end来定义结束；
• 通过关键字close可以停掉某一天，如，sunday are closed。

2.8 思维导图 (MindMap)

思维导图又名心智导图，是表达发散性思维的有效图形思维工具 ，它简单却又很有效同时又很高效，是一种实用性的思维工具。一般的思维导图及其描述语言如下：

@startmindmap
<style>
mindmapDiagram {
  node {
    BackgroundColor lightGreen
  }
  boxless {
    FontColor darkgreen
  }
}
</style>
* Linux
** NixOS
** Debian
***_ Ubuntu
**** Linux Mint
**** Kubuntu
**** Lubuntu
**** KDE Neon
@endmindmap

• 思维导图开头和结尾要用@startmindmap 和@endmindmap标记；
• 使用关键字mindmapDiagram对思维导图的样式进行定义；
• 一个*代表一个层级。*增加一个，层级就往前进。-和*是一样的，只是-代表的图形往左边生长。

2.9 工作分解结构图 (Work Breakdown Structure)

工作分解结构跟因数分解是一个原理，就是把一个项目，按一定的原则分解。项目分解成任务，任务再分解成一项项工作，再把一项项工作分配到每个人的日常活动中，直到分解不下去为止。一般的工作分解结构图及其描述语言如下：

@startwbs
@startwbs
* Business Process Modelling WBS
** Launch the project
*** Complete Stakeholder Research
*** Initial Implementation Plan
** Design phase
*** Model of AsIs Processes Completed
**** Model of AsIs Processes Completed1
**** Model of AsIs Processes Completed2
*** Measure AsIs performance metrics
*** Identify Quick Wins
** Complete innovate phase
@endwbs

• 工作分解结构图开头和结尾要用@startwbs 和@endwbs标记；
• 语法和思维导图的语法很相似，一个*代表一个层级。*增加一个，层级就往前进。

2.10 JSON可视化 (Display JSON Data)

JSON(JavaScript Object Notation, JS 对象简谱) 是一种轻量级的数据交换格式。简洁和清晰的层次结构使得 JSON 成为理想的数据交换语言。 易于人阅读和编写，同时也易于机器解析和生成，并有效地提升网络传输效率。由于JSON数据会存在嵌套，将其可视化后，会更易于观察数据。JSON数据可视化后的图片及其标记语言如下。

@startjson
#highlight "lastName"
#highlight "address" / "city"
#highlight "phoneNumbers" / "0" / "number"
{
  "firstName": "John",
  "lastName": "Smith",
  "isAlive": true,
  "age": 28,
  "address": {
    "streetAddress": "21 2nd Street",
    "city": "New York",
    "state": "NY",
    "postalCode": "10021-3100"
  },
  "phoneNumbers": [
    {
      "type": "home",
      "number": "212 555-1234"
    },
    {
      "type": "office",
      "number": "646 555-4567"
    }
  ],
  "children": [],
  "spouse": null
}
@endjson

• JSON可视化描述语言，开头和结尾要用@startwbs 和@endwbs标记；
• 使用关键字highlight*可以对选定的字段进行高亮显示。

2.11 YAML可视化 (Display YAML Data)

YAML 是一个可读性高，用来表达数据序列化的格式。YAML参考了其他多种语言，包括：C语言、Python、Perl，并从XML、电子邮件的数据格式（RFC 2822）中获得灵感。Clark Evans在2001年首次发表了这种语言，另外Ingy döt Net与Oren Ben-Kiki也是这语言的共同设计者。当前已经有数种编程语言或脚本语言支持（或者说解析）这种语言。YAML数据可视化后的图片及其标记语言如下。

@startyaml
<style>
yamlDiagram {
    highlight {
      BackGroundColor red
      FontColor white
      FontStyle italic
    }
}
</style>
#highlight "french-hens"
#highlight "xmas-fifth-day" / "partridges"

doe: "a deer, a female deer"
ray: "a drop of golden sun"
pi: 3.14159
xmas: true
french-hens: 3
calling-birds: 
	- huey
	- dewey
	- louie
	- fred
xmas-fifth-day: 
	calling-birds: four
	french-hens: 3
	golden-rings: 5
	partridges: 
		count: 1
		location: "a pear tree"
	turtle-doves: two
@endyaml

• YAML可视化描述语言，开头和结尾要用@startyaml 和@endyaml标记；
• 关键字yamlDiagram可以对渲染样式进行定义；
• 使用关键字highlight可以对选定的字段进行高亮显示。

3 总结

• 使用PlantUML工具，可以改变画图习惯。其采用描述语言来画图，可以更加专注于图片本身的内在逻辑，排除掉视觉审美和几何上的干扰，做到所想即所得；
• PlantUML工具的描述语言虽然多，但是触类旁通，大体都相似。有一定的学习成本，但是和其带来的高效、高质量相比，完全可以接收；
• PlantUML工具的在线学习网站plantuml.com/ 是进行练习甚至是直接画图的利器；
• PlantUML所支持的主题风格非常丰富，也可以自定义，完全能满足审美需求；
• 本文所陈述的PlantUML描述语言，在英文中称为domain-specific language (DSL)，字面翻译是领域特定语言。

至此，PlantUML工具的全部使用方法已经介绍完毕，希望大家能够学有所获。