引言
我是系统分析师，我的工作是设计自动化信息系统。 但是，不是，它是写文档。 我第三次不再重复“写”这个词，毕竟不是“伊利亚特”。 但是无聊的形式肯定使项目文档与古希腊诗紧密相关，尤其是在与国家客户打交道时。
在这片文字的海洋中，图表是一种创造力。 图表将在本文中讨论。 从我的角度来看，更确切地说，关于PlantUML ，这是目前创建它们的最合适的工具。
我敢肯定，至少有很多人听说过PlantUML，至少在GitHub上有超过1000颗星 。 该工具的含义非常简单，它仅允许您以描述元素和元素之间关系的文本形式指定图表（大部分使用UML表示法）。 图形视图将自动创建。 以下是活动图表示例。
start : ; if (?) then () : ; if (?) then () else () : ; endif : ////; else () stop endif stop
尽管很受欢迎，但是关于Habré的文章很少涉及该工具的实际应用。 在我看来，PlantUML不应该受到如此关注。
首先，我将告诉您为什么选择它作为可视化建模的主要工具，最后，我将给出许多建议，当我开始使用此工具时，我本人会很想听听他们的建议。
为什么选择PlantUML
从我的角度来看，在创建图表时，应将重点放在以下标准上：（1）图表应该变小或更少；（2）图表应该使用或多或少的标准符号；（3）从管理项目文档的角度来看，图表应该或多或少地方便。
在这三种情况下，均使用“较少”一词，因为在不影响本案的情况下，可以违反特定情况下的所有这些条件。 有许多以自制符号创建并完善的大型图表（同一张地铁地图 ）。 另一个问题是，此类图的创建是花费大量资源的项目。 此类资源远非总是（读取，从不）分配给创建自动化信息系统。 客户需要完美的系统，而不是完美的系统图。
不过，对我而言，这些标准是您开始绘制图表的起点。 接下来...怎么回事。
长期以来，我一直以为自己将Microsoft Visio的使用视为一个黄金分割，并在其中绘制了图表，力图尽可能接近UML。 在这种情况下，使用了一组标准的组件，因为它提供了比用于UML的专用模板更大的自由度。 此外，在Microsoft PowerPoint中绘制了一些用于在投影仪上显示的图表。
是的，您无法管理此类图表。 如果实体的名称已更改，请打开每个图并进行更改。 事实证明，它几乎很漂亮。 在表达思想上有一定的灵活性。
我还尝试了专门的业务建模工具：Rational Rose，Aris，Enterpise Architect（Sparx Systems），最重要的是Rational Rose。 问题是我工作的最终结果是文件。 从这个意义上说，如果需求发生了重大变化，您仍然需要手动浏览整个项目，然后将图重新插入到文本的正确位置。 在我看来，想一想，也许要自动化这部分似乎太复杂了，不值得付出努力。
随着PlantUML的到来，情况发生了根本变化。
一旦以文本形式创建了图表，这意味着在任何文本编辑器（我喜欢Atom和Notepad ++）中，您都可以在一组文件中找到所需的文本，甚至可以替换它们。 项目重构非常方便。 而且，文本格式使组织小组工作和跟踪版本控制系统中的更改变得容易。
在PlantUML中，创建图表的速度比任何可视化编辑器都要快（至少对我而言）。 关于此主题还有其他意见，例如， 它说在PlantUML中创建图表比在Enterpise Architect（Sparx Systems）中创建图表更长。 我认为这更多是关于品味和习惯的问题。
当我使用PlantUML代替木板（附近没有木板）时，甚至在与信息技术距离很远的人们那里，我什至都有相当成功的经验。
PlantUML足够灵活，可以使用UML表示法。 支持其所有基本元素，它为用户提供了许多在图表中自由使用的机会。 例如，在元素的内容中支持使用Wiki标记非常方便。
而且，显然，PlantUML的开发人员认为打破这种表示法并没有错。 这是此工具的一大优势。 最终，客户端不需要知道UML是否为UML-它需要了解图的含义。 导致意义感知改善的一切都是好的。
不过，PlantUML是UML，即 普遍接受的符号，标准，因此对于文档尤其是政府项目中的文档非常适用。
PlantUML不允许您创建大图表。 他自己分配元素，并且自然而然地使用大量元素，结果开始令人怀疑。 但这不是一个限制。 通常，当PlantUML开始产生不充分的结果时，您会意识到不是PlantUML不好，而是图表不好，因此最好将其分开或减少不相关细节的数量。
PlantUML图可以自动生成。 此处提供了此类用法的示例。
我们使用PlantUML自动生成数据库模式。 这种生成的功能内置在我们使用的数据库结构管理工具-2bass中 。 因此，在组装文档时，具有数据库结构的类图始终是最新的。 下图显示了一段数据库结构描述和一个自动生成的图表。
PlantUML提示
在我看来，许多人没有使用PlantUML，因为它们在初始阶段会遇到某些困难，他们认为这是根本无法克服的。 许多人都对文本的使用感到害怕，因为每个人都习惯了图形编辑器。 我希望这篇文章的建议能使您快速开始在战斗任务中使用PlantUML。
在哪里创建图表？
首先，我想提到PlantUML Web Server ，它是PlantUML项目的一部分，您可以在其中在线创建图表并与同事共享。 这是一个非常方便的功能，但是，当为项目文档创建图表时，当然不是。
PlantUML通常在Wiki引擎中使用。 在这里，编辑以标准方式进行：写入，保存文本，然后在页面上获得图片。 但是，尽管如此，在大多数情况下，将结果立即显示在图上还是很方便的：例如，图的规格写在左侧窗口中，而外观则显示在右侧窗口中。 完成的文本已经可以插入Wiki中。
PlantUML网站上有许多编辑器。 我怀疑其中一半以上不适合工作。 我最喜欢使用Atom编辑器中的PlantUML Preview插件来创建PlantUML图。 实际上，有几个这样的插件。 我喜欢PlantUML预览版，因为它不仅可以显示结果，而且可以立即（或在保存时-取决于设置）创建一个图形文件，其名称与具有图表说明的文件相对应。
即 每个图始终对应于两个文件，一个文本文件（带有图的文本说明），另一个图形（带有图的图片）。
由于我们很长时间以来一直在Asciidoctor的帮助下完成所有文档的工作（令人惊讶的是，拒绝Microsoft Word可以使它变得更容易，但这是另一篇文章的主题），因此我们通过链接插入了图片。 要使用此技术更改图片，只需打开文字说明，然后对其进行更改并保存。 您不需要通过剪贴板进行导出或复制操作。
请注意，PlantUML Preview插件在其设置中需要指定planuml.jar文件的位置，如果未安装GraphViz，则 PlantUML本身将无法工作，可以从相应的站点下载这两个应用程序。 在最新版本的PlantUML中，将逐步淘汰Graphviz，因此在不久的将来，该产品将变得更加自主。 这将简化其在自动汇编程序文档的系统中的使用。
准备图表进行打印
为了在激光打印机上进行高质量打印，必须指定参数skinparam dpi 300 。 300 dpi分辨率可提供高质量的图像，以便在激光打印机上进行打印。 否则，将以屏幕分辨率创建图片并使其看起来栅格化。 PlantUML还具有使用svg（矢量格式）的能力。 但是，与png相比，该格式受支持的要少得多，并且存在更多的问题。 如果有必要使用矢量编辑器（例如，使用Inkscape ）使图片更加清晰，我使用了svg。 但这当然是PlantUML极为罕见的用例。
要消除通常也会破坏打印外观的阴影，可以使用skinparam shadowing false参数。
另外，为了在黑白打印机上打印图表，希望它没有半色调。 使用棕色和黄色的配色方案通常不适合打印。 幸运的是，PlantUML允许您指定使用的颜色。 例如，以下选项以黑白调色板显示组件图。 单色图生成有一个特殊的参数（ skinparam单色true ），但是它只删除颜色，保留半色调。
skinparam component { borderColor black backgroundColor white ArrowColor black }
这里给出了大多数参数的列表。 如果要研究所有参数，可以使用java -jar plantuml.jar -language命令 。
元素的相对排列
从左到右的方向参数导致从左到右绘制图表元素。 不是很明显，但是，例如，对于组件图，这意味着组件将在左侧组装，而接口在右侧组装。
component " 1" as c1 component " 2" as c2 interface " 1" as i1 c1
与更高级别的元素分组。
在下图中，PlantUML已分配了组件，因此线交叉点较少。 如果我们希望按顺序显示组件，则组件的这种顺序可能是不希望的。
component " 1" as c1 component " 2" as c2 component " 3" as c3 interface " 1" as i1 c1 --() i1 c2 --( i1 interface " 2" as i2 c1 --() i2 c3 --( i2
如果我们将第二个和第三个组件分组，那么我们将实现这些组件按顺序排列。
component " 1" as c1 component " 1" { component " 2" as c2 component " 3" as c3 } interface " 1" as i1 c1 --() i1 c2 --( i1 interface " 2" as i2 c1 --() i2 c3 --( i2
组件的顺序。 一种颇具争议的方法，但它可以工作。 在以下示例中，首先显示组件2，如下所示： 在规范中它是第一位列出的。
component " 2" as c2 component " 1" as c1 interface " 1" as i1 c1
PlantUML还具有指示箭头方向的功能。 例如，要指示箭头从组件1（c1）到接口1（i1）从左到右，您需要在箭头的规格中指定字母“ r”： c1- r- （）i1 。 下面的示例清楚地表明，从组件1到界面1的箭头从左到右，从组件2到同一界面的箭头从右到左。
component " 1" as c1 component " 2" as c2 interface " 1" as i1 c1 -r-() i1 c2 -l-( i1
我认为这是一个有害的机会。 它使图的规格混乱，并且PlantUML对方向的解释可能非常奇怪。 另外，当指定从左到右的方向参数时，字母“ r”从上到下开始表示（由于顺时针位移），这完全使该方案感到困惑。
标签元素
多行文字和Wiki标记
PlantUML提供了一些很好的工具来格式化元素中的文本。
生成图表元素时，PlantUML基于文本的大小。 即 不是文本根据元素的大小而流动，而是元素的大小适合文本。
创建大文本的最简单方法是使用\ n字符。 在这种情况下，您还可以使用文本格式字符（粗体，斜体等）。
component "** 1** \n \n //****// \n* //// 1 \n* // 2//" as c1
有时没有其他选择。 但是在大多数情况下，都支持语法，使您可以指定多行文本。 例如，在前面的示例中，您可以使用此语法。
component c1 [ ** 1** ==== ..//****//.. * //// 1 * // 2// ] note left .... ** 1** ==== ..//****//.. * //// 1 * // 2// end note
如我们所见，使用此语法可以添加分隔线。 请注意，此处添加了一条注释，该注释显示与组件相同的文本。 同时，在注释中，列表显示为列表，在组件中，显示为通过“ *”符号显示的文本。 不幸的是，列表和表格在组件中不起作用。 尽管它们例如在表示活动的元素中工作（在活动图中）。
使用图标
PlantUML支持多种使用图标的方式。 它们都有一定的局限性。
在我看来，最受欢迎的技术已经成为使用所谓的Sprite的技术。 子画面是使用文本设置的位图。 该技术的最大优点是PlantUML允许您创建外部精灵库。 有几个这样的库。 我最喜欢的是PlantUML Icon-Font Sprites库，因为 它包含来自Font Awesome的图形图像。
请注意，PlantUML中的子画面是位图，即 它们在缩放方面有限制。 在此特定的库中，图标的分辨率为48 x 48像素。 当使用这种图像进行打印时，不希望将其缩放到大于5毫米的尺寸（大致对应于250 dpi的分辨率）。 在许多描述Sprite用法的Internet资源上，没有考虑到这一点，示例中的图表元素带有大图标。 在屏幕上，这些图看起来不错，但是在打印时，它们看起来已经光栅化了。
在签名内部方便使用4-5毫米的图标大小。 例如，在下图中，使用图标显示了用户角色，其成员将流程从一种状态转移到另一种状态。
' !define ICONURL https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/v2.0.0 !includeurl ICONURL/common.puml !includeurl ICONURL/font-awesome-5/user_cog.puml !includeurl ICONURL/font-awesome-5/user_check.puml !define _CS scale=0.4 !define _user_cog <$user_cog{_CS}> !define _user_check <$user_check{_CS}> ' legend ..** **.. _user_cog — _user_check — endlegend ' state " " as prepare_doc [*] --> prepare_doc state " " as check_doc prepare_doc --> check_doc : _user_cog \n \n check_doc --> prepare_doc : _user_check \n \n state " " as ready_doc check_doc --> ready_doc: _user_check \n \n<U+00AB><U+00BB>
有些图标直接内置在PlantUML中，但是我更喜欢使用外部库。 特别是，此示例中的图标包含在Awesome v5库中，并且在撰写本文时（版本1.2018.08），PlantUML中仅内置了Awesome v4库。
使用引号
事实证明，这个看似简单的问题几乎使我无法使用PlantUML。 缺少引号看起来不专业且有趣。
PlantUML支持多种使用引号的方式。 但是，由于搜索的结果，我发现只有一个总是可以使用的旧废纸：用于打开俄语报价-<U + 00AB>，用于结束报价-<U + 00BB>，用于通用报价-<U + 0022>。
如何在图表中不迷路
活动图中的语法非常方便，很难混淆，因为 它比图的描述更像是算法的描述。 但是在其他图中：状态，组件，部署，用例，类和其他图，很容易混淆。
有两个简单的规则可以帮助我避免混淆。
通过关键字输入所有元素（不要使用简化语法）。 如果元素允许，请为其设置别名。
在元素之后立即指示关系（当然，如果关联的元素已经存在于图表中）。 事实是，在文本中总是容易找到元素。 只能通过别名找到连接。 如果使用此规则，则也可以在文本中快速找到连接。
结论
PlantUML不是玩具。 这是一种高质量的通用工具，您可以使用它解决与业务流程描述和所设计系统的体系结构功能相关的几乎所有问题。
PlantUML在进入方面存在心理障碍：我们已经习惯了可视化编辑器，因此使用文本似乎向后退。 但是，如果由于这一退步而提高了工作效率，为什么不这样做呢？
PlantUML的实现存在漏洞：某些功能仅适用于部分图或图形基元。 但是，实际上，总是可以绕开这种限制。 PlantUML是一种成熟且稳定的工作产品，您可以完全依靠它来工作，而不必担心它将破坏图表或使字体变形或引发其他问题，这些问题将导致在进入下一阶段之前无法入眠。