PlantUML 结构化 JSON 展示：把配置 / API 响应 / 任意 JSON 画成树

PlantUML 的“冷门”宝藏功能：把 JSON / YAML 直接当输入源，画成结构化树图。比 Graphviz 手写 dot 简单，比 Mermaid flowchart 像样，比手画 Visio 快 50 倍。

一句话开启

1
2
3
4
5
6
7
8
9
10
11

@startjson
{
  "name": "puml.online",
  "version": "1.2.0",
  "stack": {
    "frontend": "Hexo + redefine",
    "backend": "EdgeOne Pages",
    "diagrams": ["PlantUML", "Mermaid"]
  }
}
@endjson

@startjson / @endjson 包一段标准 JSON，PlantUML 自动把它画成树状图。YAML 同理——@startyaml / @endyaml。两个指令都来自 PlantUML 的官方 stdlib，不需要额外装插件。

它解决了什么问题

画「嵌套结构图」是文档 / 调试里最高频的苦差事之一：

• 配置文件：package.json / tsconfig.json / nx.json / docker-compose.yml 的层级和字段名
• API 响应：后端实际返回的 JSON 长什么样，前端字段对不上时拿来对账
• 状态快照：把整个 Redux store / Vuex state / Pinia store dump 出来
• 领域模型：用一个真实 JSON 实例描述 schema，比 ER 图更直观
• 测试 fixture：把 mock data 画出来，确认嵌套层级没写错

以前做这些要：(a) 手抄字段到 Visio / draw.io；(b) 用 jq + dot 写脚本；(c) 直接截图 console.log。@startjson 把 (a)(c) 干掉了，(b) 也被大幅简化——脚本只负责拼 JSON 字符串，渲染交给 PlantUML。

完整语法：所有 JSON 类型都支持

JSON 里的 6 种值类型 PlantUML 都能识别并差异化渲染：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

@startjson
{
  "string": "文本值",
  "number": 42,
  "boolean": true,
  "null_value": null,
  "array": [
    "第一个",
    "第二个",
    {"nested_in_array": "对象也能塞数组里"}
  ],
  "object": {
    "depth_2": {
      "depth_3": "任意深度都画得动"
    }
  }
}
@endjson

渲染出来的样子：

• 字符串 → 浅色背景 + 引号
• 数字 → 蓝色
• 布尔 → 紫色，true / false 区分
• null → 灰色，斜体
• 数组 → 自动展开成 <array> 节点，下面挂 [0]、[1]…
• 对象 → 自动展开成 <object> 节点，下面挂字段名

高亮与样式：让重点一眼可见

单节点高亮

#highlight 标记某个 key，让它和兄弟节点视觉上区分开：

1
2
3
4
5
6
7
8

@startjson
#highlight "version"
{
  "name": "puml.online",
  "version": "1.2.0",
  "deprecated": false
}
@endjson

version 节点会变成橘黄色背景。

多个 key 高亮

1
2
3
4
5
6
7
8
9

@startjson
#highlight "version"
#highlight "deprecated"
{
  "name": "puml.online",
  "version": "1.2.0",
  "deprecated": false
}
@endjson

给整个 JSON 上色

#highlight 后跟整个 JSON（不带 key），所有节点统一变色：

1
2
3
4
5
6
7

@startjson
#highlight
{
  "all": "everything turns pink",
  "you": "might not want this"
}
@endjson

条件高亮（满足条件才高亮）

1
2
3
4
5
6
7

@startjson
#highlight "deprecated" : false
{
  "deprecated": false,
  "active": false
}
@endjson

只有 deprecated 节点值是 false 时才被高亮——active: false 不变色。适合「找所有 enabled=false 的字段」之类场景。

真实案例：把 package.json 画出来

下面是一个 React 项目的 package.json，直接 @startjson 包起来就是一张可读的依赖 / 脚本图：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

@startjson
{
  "name": "my-react-app",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "test": "vitest",
    "lint": "eslint . --ext .ts,.tsx"
  },
  "dependencies": {
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-router-dom": "^6.26.0",
    "zustand": "^4.5.4"
  },
  "devDependencies": {
    "vite": "^5.4.0",
    "typescript": "^5.5.0",
    "@types/react": "^18.3.0",
    "vitest": "^2.0.0"
  }
}
@endjson

把这一段贴在 README 里，比纯文本 JSON 直观 10 倍——新人 onboarding 第一眼就能看到「哪些是运行依赖、哪些是开发依赖、构建命令是什么」。

真实案例：API 响应对账

后端给的真实响应，调试时直接 dump 出来：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

@startjson
#highlight "status"
#highlight "user.email_verified" : false
{
  "status": 200,
  "data": {
    "user": {
      "id": 12345,
      "email": "alice@example.com",
      "email_verified": false,
      "role": "admin",
      "created_at": "2025-06-12T08:33:21Z"
    },
    "session": {
      "token": "eyJhbGciOi...",
      "expires_at": "2025-07-12T08:33:21Z"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "server": "api-3"
  }
}
@endjson

status 和「未验证的 email」节点高亮——一眼看出「调用成功但账号未验证」。这张图直接贴 issue 评论比文字描述高效得多。

JSON 大/丑的时候怎么办

直接 @startjson 套 1000 行 JSON 会画得很挤。三个常用技巧：

1. 用 %json 指令控制格式

1
2
3
4
5

@startjson
{
  "key": "value"
}
@endjson

PlantUML 默认会把过长的字符串截断（30 字符 + ...）。完整字符串依然在 SVG 里（选中复制可拿到），但视图上不会撑爆图。

2. 数组很长时让它换行

1
2
3
4
5
6
7
8
9

@startjson
{
  "bigArray": [
#highlight "0" : "first"
    "a", "b", "c", "d", "e", "f", "g", "h",
    "i", "j", "k", "l", "m", "n", "o", "p"
  ]
}
@endjson

数组节点默认垂直排列（节省宽度）。横向紧凑模式在大型 JSON 里更难读，别用。

3. 嵌套太深时抽变量

1
2
3
4
5
6
7
8
9
10
11
12
13

@startuml
!$cfg = %json("{" +
  "  \"name\": \"demo\"," +
  "  \"children\": [" +
  "    {\"id\": 1, \"name\": \"a\"}," +
  "    {\"id\": 2, \"name\": \"b\"}" +
  "  ]" +
  "}")

@startjson
%$cfg
@endjson
@enduml

把 JSON 字符串丢给 %json() 函数预处理后再 @startjson 引用——避免长字符串转义把 .puml 文件搞得一团乱。!$var = ... 是 PlantUML 预处理器赋值语法，%json() 是 stdlib 提供的 JSON 解析函数。

JSON vs YAML vs JSON5：都支持

1
2
3
4
5
6
7
8
9
10

@startyaml
name: puml.online
stack:
  frontend: Hexo + redefine
  backend: EdgeOne Pages
features:
  - live preview
  - SVG export
  - PNG export
@endyaml

@startyaml / @endyaml 是 JSON 的孪生兄弟。YAML 写起来更紧凑（不用引号、不用花括号），嵌套一多时阅读性比 JSON 还好。两种指令生成的图视觉上完全一致。

PlantUML 还支持 JSON5（带注释、尾逗号、单引号的 JSON 扩展）——只要把 @startjson 换成 @startjson5 / @endjson5。如果你团队用的是 .jsonc 配置文件（VSCode 的 settings.json / tsconfig.json），可以直接粘贴进来。

跟其他工具的对比

Mermaid 没有原生 JSON 指令——它要你手写 flowchart，或者用 mermaid 的 sankey / mindmap 近似，但都不如 PlantUML 这个干净。

一些“坑”和边角

1. JSON 里的转义字符

如果 JSON 里有 \" 或 \\，包在 @startjson 里时不需要再转义一层——PlantUML 解析时按字符串字面量处理。但如果你用预处理器变量（!$var = "..."），就要双重转义。

2. 注释

PlantUUMl 在 JSON/YAML 块里不支持注释——写了会报错。注释放在外面用 ' comment。

3. 大文件

字段数超过 ~500 渲染会显著变慢（dot 引擎的极限）。超过这个量考虑：(a) 只画关键子树；(b) 用 jq 预处理把不关心的字段剔掉再贴。

4. 重复 key

JSON 标准不允许重复 key，但 PlantUML 解析器会接受，渲染时只保留最后一个。代码评审别放过这种 bug。

实战工作流

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 1. 从 API 拉响应
curl -s https://api.example.com/v1/me \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o response.json

# 2. 包成 PlantUML 块
{
  echo '@startjson'
  cat response.json
  echo '@endjson'
} > diagram.puml

# 3. 渲染（本地有 plantuml CLI 时）
plantuml -tsvg diagram.puml

或者直接贴进 puml.online 的编辑器——所见即所得。

什么时候不用

• 数据库 schema 演进：用 ER 图（@startuml + entity）比 JSON 实例清晰
• 类层次结构：用类图
• 调用关系 / 流程：用时序图或活动图
• JSON 结构本身是文档主题：用 @startjson 最合适

简单说：你要展示「一段真实数据的形状」就用 JSON 图；展示「类型之间的关系」就用 UML 图。

小结

@startjson 是 PlantUML 最被低估的功能之一：

• 一行指令把任意 JSON / YAML 变成可读树图
• 支持全部 6 种 JSON 值类型自动差异化渲染
• #highlight 让重点 key 一眼可见，条件高亮适合「找所有 X=false 的字段」
• 真实场景：配置文件结构、API 响应、状态快照、测试 fixture
• 比 Graphviz / Mermaid 手写流程图快 5-10 倍

把它加入你的文档工具箱，下次有人问你「package.json 里 dependencies 和 devDependencies 有什么区别」——直接画一张图甩过去，比解释 10 分钟更有效。