代码即文档之PlantUML

背景

对于大型项目而言，技术文档至关重要。新加入项目的成员往往需要查阅文档以理解项目背景和业务场景，从而明白系统的功能。即使是经验丰富的项目成员，也很难记住如此庞大的上下文，因此仍需要文档的辅助。因此，技术文档对于后续功能开发、重构及定位错误都具有至关重要的作用。

然而，对于程序员而言，日常代码工作已经十分繁重，同时维护代码和文档两套上下文也颇具挑战。这往往导致文档方面存在疏漏，最终使得留存文档失去维护，从而使后续查阅文档的人员无法获得完整、正确的上下文。因此，采用程序员更易维护的方式编写技术文档，以减少文档与代码间的重复工作显得尤为重要。

在此背景下，'代码即文档' 的概念日益流行。程序员可以利用自己熟悉的代码方式来维护和编写文档，无需繁琐地调整文档格式。在编写时序图、类图、状态转换图、组件图等文档时，我首选的工具是——PlantUML。

介绍

PlantUML是一个多功能组件，可快速、直接地创建图表。用户可以使用简单直观的语言起草各种图表。支持UML图表或者非UML图表的绘制，可以插入超链接或者图表、数学表达式等。最重要的是支持输出为PNG格式，这样就可以在绘制图表后直接输出为更容易阅读的格式。

官方文档：https://plantuml.com/zh/

环境

• IntelliJ IDEA
• Plugins：PlantUML Integration
• Graphviz

示例

类图

参考官方文档示例：https://plantuml.com/zh/class-diagram

@startuml
class Zoo {
    - List<Animal> animals
}

Class Animal {
    - String name
    - Integer amount
}

class Monkey extends Animal
class Bear extends Animal
class Tiger extends Animal
Zoo *-- Animal
@enduml

流程图/活动图

参考官方文档示例：https://plantuml.com/zh/activity-diagram-beta

@startuml
start
repeat
  :计算订单总价格;
    if (该商品库存为0?) then (没有)
      :加上该商品价格;
      break
    endif
    ->not ok;
    :不加该商品价格并将其从订单中删除;
repeat while (订单中还有未计算的商品?) is (是的) not (不是)
->//计算所有价格并生成订单//;
:展示订单总价格给用户;
stop
@enduml

时序图

参考官方文档示例：https://plantuml.com/zh/sequence-diagram

@startuml
App -> Backend: 请求支付账单
Backend -> 第三方支付组件: 发起支付请求

第三方支付组件 --> Backend: 返回支付链接
Backend --> App: 返回支付链接
@enduml

状态转换图

参考官方文档示例：https://plantuml.com/zh/sequence-diagram

@startuml
DRAFT: 文章创建后

DRAFT --> ONLINE
note on link
后台发布文章
end note
OFFLINE --> ONLINE
note on link
后台发布文章
end note
ONLINE: 文章发布后

ONLINE --> OFFLINE
note on link
后台下架文章
end note
OFFLINE: 文章下架后

DRAFT --> DELETED
note on link
后台删除文章
end note
DELETED: 文章被删除后
@enduml