PlantUML as a document

sorcererxw /

最近参与了几个新项目的设计,需要编写不少设计文档编写,比如类图、流程图。当然有很多不错的绘图工具,如 visio、starUML、draw.io 等。不过他们都有一个致命的缺陷(至少对我而言),那就是他们都完全依赖于 GUI 操作,不能依赖于 DSL 进行编写图例。这样的方式有几个问题:

  • 效率低。鼠标拖拖点点速度肯定比不上键盘输入。
  • 需要打开外部工具进行编辑,而不能在编辑器内完成文档编写,这种割裂感挺影响设计思路的。
  • 无法将图例设计纳入版本管理

于是在网上找了半天,找到了一个 PlantUML 这种格式。这是一种依赖于 DSL 来绘制 UML 图的工具。可以理解为类似 Markdown,使用特定的标记语言,来增强普通文本的可视效果。

其实 PlantUML 已经被很多 Markdown 编辑器纳入标准了,可以直接在 Markdown 当中插入 PlantUML 并渲染。只不过 Github 现在还不支持,所以我们在编写文档的时候,还是需要专门创建 ***.puml 来编写。

这里推荐一下一个 IDEA 下的小工具:PlantUML integration。可以在编写图例的时候,实时在边上渲染效果。

PlantUML Integration - IntelliJ IDEs Plugin | Marketplace
PlantUML diagramming tool integration. Now better and faster, with code navigation and highlighting.
https://plugins.jetbrains.com/plugin/7017-plantuml-integration/

PlantUML 支持很多类型图示,可以说是非常强大。可以直接去参考中文文档。

PlantUML 是一个开源项目,支持快速绘制:时序图 用例图 类图 活动图 组件图 状态图 对象图 部署图 定时图 
同时还支持以下非 UML 图:线框图形界面 架构图 规范和描述语言 (SDL) Ditaa diagram 甘特图 思维导图 Work Breakdown Structure diagram 以 AsciiMath 或 JLaTeXMath 符号的数学公式 Entity Relationship diagram
开源工具,使用简单的文字描述画UML图。
轻松从简单的文字说明创建UML图。也有许多种可用的图表。它也可以在PNG,乳胶,EPS,SVG图像导出。
http://plantuml.com/zh/

最后要说一些如何进行文档集成和管理 PlantUML。

一般这类工程文档非常适合同代码一起使用 Git 进行管理,我也是这么做的。但是 github 并不支持渲染 PlantUML,难道使用 github 查阅文档的时候,还需要将 PlantUML 文档下载下来,然后使用 plantuml 工具渲染出图片么?答案是否定的,PlantUML 已经为我们提供了解决方案 — PlantUML Server,服务端可以直接渲染出图片提供给前端显示。并且 www.plantuml.com 也免费提供了渲染服务。

https://www.plantuml.com/plantuml/proxy?src=RESOURCE&idx=INDEX&fmt=FORMAT

  • src: puml 源文档地址,如果文档托管在 github 上,那么直接拿到文件的 cdn 地址即可。
  • idx: 如果文档内包含多个 UML 块(以 @startuml 开始,以 @enduml 结束),那么可以用 idx 指定渲染哪一个 UML。
  • fmt: 输出格式,默认是 png。可能是因为服务器限制了最大文件体积,那么渲染成 png 可能存在图片不完整的问题。建议设置为 svg,一来降低带宽消耗,二来使图片不论在什么地方显示都足够清晰。

这样子一来,我们就可以将 PlantUML 使用图片的方式直接插入 Github 上的 Markdown 文档内了。