PlantUML as a document
最近参与了几个新项目的设计，需要编写不少设计文档编写，比如类图、流程图。当然有很多不错的绘图工具，如 visio、starUML、draw.io 等。不过他们都有一个致命的缺陷（至少对我而言），那就是他们都完全依赖于 GUI 操作，不能依赖于 DSL 进行编写图例。这样的方式有几个问题：
- 效率低。鼠标拖拖点点速度肯定比不上键盘输入。
- 需要打开外部工具进行编辑，而不能在编辑器内完成文档编写，这种割裂感挺影响设计思路的。
- 无法将图例设计纳入版本管理。
于是在网上找了半天，找到了一个 PlantUML 这种格式。这是一种依赖于 DSL 来绘制 UML 图的工具。可以理解为类似 Markdown，使用特定的标记语言，来增强普通文本的可视效果。
其实 PlantUML 已经被很多 Markdown 编辑器纳入标准了，可以直接在 Markdown 当中插入 PlantUML 并渲染。只不过 Github 现在还不支持，所以我们在编写文档的时候，还是需要专门创建 ***.puml 来编写。
这里推荐一下一个 IDEA 下的小工具：PlantUML integration。可以在编写图例的时候，实时在边上渲染效果。
PlantUML 支持很多类型图示，可以说是非常强大。可以直接去参考中文文档。
PlantUML 是一个开源项目，支持快速绘制：时序图 用例图 类图 活动图 组件图 状态图 对象图 部署图 定时图
同时还支持以下非 UML 图：线框图形界面 架构图 规范和描述语言 (SDL) Ditaa diagram 甘特图 思维导图 Work Breakdown Structure diagram 以 AsciiMath 或 JLaTeXMath 符号的数学公式 Entity Relationship diagram
最后要说一些如何进行文档集成和管理 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 文档内了。