PlantUML 语法 - 云多面

PlantUML 语法验证

这篇文章用于验证博客 Markdown 中的 plantuml / puml 代码块能否被服务端本地渲染为 SVG，并正确嵌入到文章内容中。

在 Markdown 中使用三反引号代码块即可触发渲染：

```plantuml
@startuml
Alice -> Bob: Hello
@enduml
```

也可以使用 puml 作为语言标识：

```puml
@startuml
Alice -> Bob: Hello
@enduml
```

时序图

时序图适合描述用户、浏览器、服务端、外部系统之间的调用链路。

语法：

```plantuml
@startuml
actor 用户
participant 浏览器
participant Remix3
participant Markdown渲染器
participant PlantUML本地CLI

autonumber
用户 -> 浏览器: 打开博客文章
浏览器 -> Remix3: 请求文章 HTML
Remix3 -> Markdown渲染器: 解析 Markdown
Markdown渲染器 -> PlantUML本地CLI: 渲染 PlantUML 代码块
PlantUML本地CLI --> Markdown渲染器: 返回 SVG
Markdown渲染器 --> Remix3: 返回文章 HTML
Remix3 --> 浏览器: 响应页面
浏览器 --> 用户: 展示 SVG 图表
@enduml
```

效果：

类图

类图适合表达实体结构、字段、方法和依赖关系。

语法：

```puml
@startuml
class BlogPost {
  +slug: string
  +title: string
  +summary: string
  +tags: string[]
  +html: string
}

class BlogRepository {
  +getPosts(tag?: string)
  +getTags()
  +getPost(slug: string)
}

class MarkdownRenderer {
  +render(body: string)
}

class RenderCache {
  +read(key: string)
  +write(key: string, html: string)
}

BlogRepository --> BlogPost
BlogRepository --> MarkdownRenderer
MarkdownRenderer --> RenderCache
@enduml
```

效果：

组件图

组件图适合描述模块边界与依赖关系。

语法：

```plantuml
@startuml
package "Remix3 应用" {
  [Blog Route] as Route
  [Blog Repository] as Repository
  [Markdown Processor] as Processor
  [Render Cache] as Cache
}

database "vb-posts Git 仓库" as Posts
component "PlantUML CLI/JAR" as PlantUML
component "Playwright + Mermaid" as Mermaid

Route --> Repository
Repository --> Posts
Repository --> Processor
Processor --> Cache
Processor --> PlantUML
Processor --> Mermaid
@enduml
```

效果：

用例图

用例图适合从用户视角表达系统能力。

语法：

```plantuml
@startuml
left to right direction
actor 访客
actor 作者
rectangle 博客系统 {
  访客 -- (浏览文章列表)
  访客 -- (阅读文章详情)
  访客 -- (查看图表)
  作者 -- (编写 Markdown)
  作者 -- (提交到 vb-posts)
  (阅读文章详情) ..> (渲染 Mermaid) : include
  (阅读文章详情) ..> (渲染 PlantUML) : include
}
@enduml
```

效果：

活动图

活动图适合描述流程、分支和回退策略。

语法：

```plantuml
@startuml
start
:收到文章详情请求;
:同步 vb-posts 仓库;
:读取 Markdown 文件;
if (命中文章渲染缓存?) then (是)
  :返回缓存 HTML;
else (否)
  :解析 Markdown;
  if (存在 PlantUML 代码块?) then (是)
    if (命中 PlantUML SVG 缓存?) then (是)
      :读取 SVG 缓存;
    else (否)
      :调用本地 CLI/JAR 生成 SVG;
      :写入 SVG 缓存;
    endif
  endif
  :生成文章 HTML;
  :写入文章渲染缓存;
endif
:响应页面;
stop
@enduml
```

效果：

状态图

状态图适合表达缓存对象或业务对象的生命周期。

语法：

```plantuml
@startuml
[*] --> Missing
Missing --> Rendering : 首次请求
Rendering --> Ready : 渲染成功
Rendering --> Failed : 渲染失败
Ready --> Stale : Markdown blob 变化
Stale --> Rendering : 重新请求
Failed --> Rendering : 下次重试
Ready --> [*]
@enduml
```

效果：

思维导图

思维导图适合组织主题、能力清单和知识结构。

语法：

```plantuml
@startmindmap
* 博客渲染
** Markdown
*** frontmatter
*** GFM
*** HTML
** 图表
*** Mermaid
*** PlantUML
** 缓存
*** SVG 缓存
*** 文章 HTML 缓存
*** Git blob 版本
@endmindmap
```

效果：

甘特图

甘特图适合表达任务顺序和里程碑。

语法：

```plantuml
@startgantt
printscale daily
project starts 2026-06-24
[完善 PlantUML 文档] lasts 5 days
[实现文章渲染缓存] lasts 5 days
[验证博客详情页] lasts 3 days
[提交主项目变更] lasts 2 days
[实现文章渲染缓存] starts at [完善 PlantUML 文档]'s end
[验证博客详情页] starts at [实现文章渲染缓存]'s end
[提交主项目变更] starts at [验证博客详情页]'s end
@endgantt
```

效果：

JSON 图

PlantUML 也可以渲染结构化数据，适合展示配置或接口数据示例。

语法：

```plantuml
@startjson
{
  "cache": {
    "type": "markdown-render",
    "key": "slug + git blob + renderer version",
    "format": "json",
    "payload": ["meta", "html"]
  }
}
@endjson
```

效果：

小结

这篇文章覆盖了 PlantUML 的常用图形：时序图、类图、组件图、用例图、活动图、状态图、思维导图、甘特图和 JSON 图。它可以作为博客渲染链路的回归测试文档，用于验证：

plantuml 与 puml 代码块识别；
本地 PlantUML CLI/JAR 渲染；
SVG 缓存命中；
inline SVG 在文章中的展示；
Markdown 整体渲染缓存是否正确失效。

PlantUML 语法验证

时序图

类图

组件图

用例图

活动图

状态图

思维导图

甘特图

JSON 图

小结

标签