Markdown 中 PlantUML 图表指南
PlantUML 是一种使用纯文本描述图表的工具。你只需要写一段结构化语法，就可以生成时序图、类图、用例图、活动图等常见工程图。
它特别适合写在技术博客和项目文档里：
- 图表和正文一起版本管理，便于协作与审阅
- 修改图只需要改文本，适合频繁迭代
- 能和 Markdown 无缝结合，保持文档统一
在 Firefly 中，plantuml 代码块会在构建阶段编码并生成服务器 SVG 地址，页面端再根据亮暗主题自动切换图源，并支持缩放、拖拽和全屏交互。
如果你想快速上手，可以记住这个最小模板：
1@startuml
2Alice -> Bob: Hello
3Bob --> Alice: Hi
4@enduml
活动图示例
1@startuml
2start
3:用户提交订单;
4if (库存充足?) then (是)
5 :冻结库存;
6 :创建支付单;
7 if (支付成功?) then (是)
8 :生成发货单;
9 :通知仓库拣货;
10 else (否)
11 :取消订单;
12 :释放库存;
13 endif
14else (否)
15 :提示缺货;
16endif
17stop
18@enduml
状态图示例
1@startuml
2[*] --> 草稿
3
4草稿 --> 待审核 : 提交
5待审核 --> 草稿 : 驳回
6待审核 --> 已发布 : 审核通过
7已发布 --> 已归档 : 到期归档
8已发布 --> 草稿 : 撤回修改
9
10state 已发布 {
11 [*] --> 可见
12 可见 --> 隐藏 : 手动隐藏
13 隐藏 --> 可见 : 恢复展示
14}
15
16已归档 --> [*]
17@enduml
用例图示例
1@startuml
2left to right direction
3actor 游客
4actor 用户
5actor 管理员
6
7rectangle 博客系统 {
8 usecase "浏览文章" as UC1
9 usecase "搜索内容" as UC2
10 usecase "发表评论" as UC3
11 usecase "点赞收藏" as UC4
12 usecase "审核评论" as UC5
13 usecase "发布文章" as UC6
14}
15
16游客 --> UC1
17游客 --> UC2
18用户 --> UC1
19用户 --> UC2
20用户 --> UC3
21用户 --> UC4
22管理员 --> UC5
23管理员 --> UC6
24@enduml
组件图示例
1@startuml
2package "Firefly Site" {
3 [Astro App] as App
4 [Markdown Parser] as Parser
5 [PlantUML Encoder] as Encoder
6 [Theme Switcher] as Theme
7 [Search Indexer] as Search
8}
9
10cloud "PlantUML Server" as PU
11database "Content Store" as Content
12
13App --> Parser : parse markdown
14Parser --> Encoder : encode plantuml blocks
15Encoder --> PU : request svg
16App --> Theme : switch dark/light src
17App --> Search : build page index
18Parser --> Content : read posts
19@enduml
部署图示例
1@startuml
2node "User Device" {
3 artifact "Browser"
4}
5
6node "CDN / Edge" {
7 artifact "Static Assets"
8}
9
10node "Cloudflare Worker" {
11 artifact "SSR Handler"
12}
13
14node "PlantUML Service" {
15 artifact "SVG Renderer"
16}
17
18database "Object Storage" {
19 artifact "Markdown Content"
20}
21
22"Browser" --> "Static Assets" : GET js/css/img
23"Browser" --> "SSR Handler" : request page
24"SSR Handler" --> "Markdown Content" : read post
25"Browser" --> "SVG Renderer" : fetch diagram svg
26@enduml
ER 图示例
1@startuml
2entity User {
3 *id : uuid <<PK>>
4 --
5 username : varchar
6 email : varchar
7 created_at : datetime
8}
9
10entity Post {
11 *id : uuid <<PK>>
12 --
13 author_id : uuid <<FK>>
14 title : varchar
15 content : text
16 published_at : datetime
17}
18
19entity Comment {
20 *id : uuid <<PK>>
21 --
22 post_id : uuid <<FK>>
23 user_id : uuid <<FK>>
24 body : text
25 created_at : datetime
26}
27
28User ||--o{ Post : writes
29User ||--o{ Comment : creates
30Post ||--o{ Comment : has
31@enduml
时序图示例（登录与刷新令牌）
1@startuml
2autonumber
3actor User as 用户
4participant Web as 前端页面
5participant API as 网关接口
6participant Auth as 认证服务
7database Redis as 会话缓存
8
9用户 -> 前端页面 : 输入账号密码并提交
10前端页面 -> 网关接口 : POST /login
11网关接口 -> 认证服务 : 校验凭据
12认证服务 -> 会话缓存 : 写入 refresh_token
13认证服务 --> 网关接口 : access_token + refresh_token
14网关接口 --> 前端页面 : 200 登录成功
15
16... access_token 过期 ...
17
18前端页面 -> 网关接口 : POST /refresh
19网关接口 -> 认证服务 : 校验 refresh_token
20认证服务 -> 会话缓存 : 轮换 refresh_token
21认证服务 --> 网关接口 : 新 access_token
22网关接口 --> 前端页面 : 200 新令牌
23@enduml
C4 风格容器图示例
1@startuml
2!includeurl https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
3
4Person(user, "博客访客", "阅读文章与搜索内容")
5
6System_Boundary(system, "Firefly Blog") {
7 Container(web, "Web App", "Astro + Svelte", "渲染页面与交互")
8 Container(worker, "SSR Worker", "Cloudflare Workers", "处理服务端渲染请求")
9 ContainerDb(content, "Content Store", "Markdown / Object Storage", "存储文章与资源元数据")
10 Container(search, "Search Index", "Pagefind", "提供全文检索")
11}
12
13System_Ext(plantuml, "PlantUML Server", "生成 SVG 图表")
14
15Rel(user, web, "访问", "HTTPS")
16Rel(web, worker, "请求 SSR 页面", "HTTPS")
17Rel(worker, content, "读取文章")
18Rel(web, search, "查询关键词")
19Rel(web, plantuml, "请求图表 SVG")
20
21LAYOUT_LEFT_RIGHT()
22@enduml
留言评论
期待你的想法评论加载中