介绍 PlantUML

2022-05-06, 星期五, 10:52

简介

PlantUML 是一个可以快速编写 UML 图的工具，支持绘制：

顺序图
用例图
类图
对象图
组件图
部署图
状态图
时序图

也支持一些非 UML 图如：

网络图
线框图形界面或 UI 模拟
架构图
规范和描述语言（SDL）
Ditaa 图
甘特图
思维导图
工作分解结构图（WBS）
AsciiMath 或 JLaTeXMath 数学符号
实体关系图 (IE/ER)

安装与使用

通过 java -jar plantuml.jar $file 可直接使用，macOS 也可通过 brew install plantuml 安装。

如果指定了一个目录，PlantUML 会搜索这个目录下的所有 .txt，.tex，.java，.htm，.html，.c，.h，.cpp，.apt，.pu，.puml，.hpp，.hh 或 .md 文件，查找被 @startXYZ 和 @endXYZ 包围的内容。

命令行参数

默认生成 PNG 文件，可以通过 -tsvg 参数生成 SVG 文件。

使用 -o 来指定输出目录，可以使用绝对路径或相对路径（相对源文件）。

生成失败时，PlantUML 会返回 -1，如果在进行批量操作，可以使用 -failfast 在出现错误时停下，也可以使用 -failfast2 在创建任何输出前先进行一次检查。

PlantUML 默认会在生成文件中保存 DSL、创建环境等元数据，使用 -nometadata 可以移除这些信息。

使用 -pipe 可以通过标准输入接收图表描述，并生成文件到标准输出。在本地文件系统上不会写任何文件。

// 一个通过 Node.js 运行的示例
const { exec } = require('child_process');
exec(
  'cat ./mindmap.wsd | plantuml -tsvg -pipe -nometadata -failfast2',
  (error, stdout, stderr) => {
    if (error) {
      console.error(`exec error: ${error}`);
      return;
    }
    console.log(`stdout: ${stdout}`);
    console.error(`stderr: ${stderr}`);
  });

让生成的图像更清晰

可以输出 SVG 图像，矢量图在放大后仍然会保持清晰
使用 skinparam dpi 300 设置图像的 dpi

如果使用了一些外部库，不能保证这些资源是清晰的。

标准库

可以使用如下命令列出 plantuml 支持的标准库

@startuml
stdlib
@enduml

绘制系统架构图

awslib 是一组适用于 PlantUML 的 AWS 图标库，而 C4 Model 常用于绘制系统架构图，下面将简要介绍如何使用这两个标准库。

@startuml Showcase

!include <awslib/AWSCommon>
' 也可以使用简化版
' !include <awslib/AWSSimplified>
!include <awslib/General/Users>
!include <awslib/ApplicationIntegration/APIGateway>

!include <C4/C4_Container>

Users(users, "Users", "millions of users")

System_Boundary(system, "System") {
    package "Showcase package" {
        APIGateway(api, "API", "/post/{id}")
    }
}

users --> api

@enduml

需要预先 !include 要使用的图标，对应的文件名可以在此处查找。如果引用了一个包下的多个图标，可以使用 all，如 !include <awslib/ApplicationIntegration/all>。

awslib/AWSSimplified 可以省略一些标注信息，如果找不到完全对应的图标就可以使用简版减少一些干扰。

Entity2DDL

这里提供了一个例子可以从类图生成数据库 DDL，也许可以参考 markdown-it 的方案实现。