HomeBlogProjects

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. Sponsored by: Manage pull requests and conduct code reviews in...
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

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