烦恼一般都是想太多了。

0%

使用C4-PlantUML来快速的描述软件架构

我们在文章 Graphviz的简单使用-画图 已经怎么知道用 dot 来描述图,然后用 graphviz 来进行绘制了。但是其实这样做非常的灵活,但是呢,灵活和方便是相互矛盾的。就有很多的人基于 graphviz 来构建了更方便的工具。

PlantUML

PlantUML 是一个基于 Graphviz 的工具,其能快速的绘制 时序图,活动图,类图等图,其使用自己定义的直观的语法来描述图。就我所感觉的话,其应该也是将自己的语法转换成了 graphviz 的语法,然后进行转换的。不过其封装了很多可用的东西,比如封装很多的图节点,这样我们就不用手动的去定义一个图示的节点了。

C4

所以的 C4 模型,指的是在四个不同的层面对系统进行描述,网站可以看这里

  1. Context: 一个设置场景的高等级的图标。包括了关键的系统依赖和人(actors/roles/personas/etc)。上下文图标 存在于软件工程中(即时我们没有使用它)
  2. Container: 一个容器图表展示了高等级的技术选择,如何将责任分发给不同的容器以及容器间如何进行通信。
  3. Component: 对于每个容器,一个组件图表让我们看到其内部的关键组件及组件间的关系。
  4. Classes (or Code): 代码层面的关系。有可能不会使用。

C4-PlantUML

C4-PlantUML 是一个 puml 代码封装库,他将 PlantUML 和 C4 模型结合起来,可以让我们更简单的描述和与软件架构通信。也即是说你对 PlantUML 使用 C4 模型进行了很多封装,让我们可以很容易的用起来。

这个的关键在于他提供了三个文件:

  • C4_Context 这里面定义了几个宏:Person, Person_Ext, System, System_Ext, SystemDb, SystemDb_Ext, Boundary, System_Boundary, Enterprise_Boundary

  • C4_Container.pumlContainer, ContainerDb, Container_Boundary

  • C4_ComponentComponent, ComponentDb

我们在使用的使用 !includeurl 链接 或者 !include 本地文件 的形式将这几个文件引入就行了。然后我们就可以使用这些定义好的宏来进行定义文件了。

其在 这里 对 C4 的一个定义进行了实现。

@startuml C4_Elements
!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/release/1-0/C4_Container.puml

Person(personAlias, "Label", "Optional Description")
Container(containerAlias, "Label", "Technology", "Optional Description")
System(systemAlias, "Label", "Optional Description")

Rel(personAlias, containerAlias, "Label", "Optional Technology")
@enduml

img

我们还可以定义系统的边界:

@startuml Basic Sample
!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/release/1-0/C4_Container.puml

Person(admin, "Administrator")
System_Boundary(c1, "Sample System") {
Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines")
}
System(twitter, "Twitter")

Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml

img

VS code 代码片段

项目内还有针对性的一些代码片段,帮助我们快速的编写文档。