JSON / YAML 转图：把配置与 API 数据画成结构图

简介

配置和接口返回值的原文读起来很费劲：一个订单 JSON 展开是十几行缩进，YAML 部署清单更是几十行嵌套。两种引擎各有办法把这种”纯数据”变成结构图——PlantUML 提供 @startjson / @startyaml 原生指令，自动把数据渲染成树；Mermaid 没有内置 JSON 解析，但可以用流程图把层级关系手写出来，反而更灵活。本文用同一份订单 JSON 分别画出两版结果，并说明什么时候该用哪一种。

PlantUML 版

PlantUML 有专门的数据图类型：@startjson 包 JSON，@startyaml 包 YAML，渲染结果是带字段名的树形结构，缩进层级自动对应嵌套层级。

@startjson
{
  "id": "ORD-2026-1042",
  "status": "PAID",
  "customer": {
    "name": "Alice",
    "tier": "gold"
  },
  "items": [
    { "sku": "P-001", "qty": 2, "price": 49.99 },
    { "sku": "P-002", "qty": 1, "price": 99.00 }
  ],
  "total": 198.98
}
@endjson

要点：

不需要额外声明：数据体原样粘贴进去，字段名成为节点名。
数组会展开成并列子节点：items 数组的两个元素变成同级分支。

YAML 同理：把 @startjson / @endjson 换成 @startyaml / @endyaml，内容不变。例如一段 K8s 部署清单：

@startyaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: my-app
          image: my-app:1.0
@endyaml

注意：不要把 JSON 放进 @startuml 里——那会被当成普通 UML 文本解析，输出乱码。

Mermaid 版

Mermaid 没有 JSON 指令，但流程图的”节点 + 箭头”天然适合表达树形结构。做法是把每个对象当一个节点、每个字段当一条边。

flowchart TD
  ROOT["ORD-2026-1042"] --> status["status = PAID"]
  ROOT --> customer["customer"]
  customer --> name["name = Alice"]
  customer --> tier["tier = gold"]
  ROOT --> items["items (2)"]
  items --> i1["P-001 x2 @ 49.99"]
  items --> i2["P-002 x1 @ 99.00"]
  ROOT --> total["total = 198.98"]

要点：

节点标签用方括号：写成 ROOT["ORD-2026-1042"] 而不是 ROOT[ORD-2026-1042]，带空格的文本才不会被截断。
flowchart TD 是纵向布局，LR 变横向；大结构用 LR 更省横向空间。
数组节点可以自己概括：items (2) 表示两个元素，再往下挂具体条目——Mermaid 不会自动展开数组，这个”摘要 + 展开”的层次更接近人的阅读习惯。

subgraph 可以框住同一层：

flowchart TD
  subgraph A["customer"]
    direction TB
    A1["name = Alice"]
    A2["tier = gold"]
  end
  ROOT["ORD-2026-1042"] --> A

不要用 JSON 字符串直接塞进标签：{"a": 1} 里的引号和大括号会被 Mermaid 当语法解析，写进标签前必须替换成普通文本。

对比

维度	PlantUML	Mermaid
原生数据支持	`@startjson` / `@startyaml` 自动成树	无，需手写流程图节点与边
数据改动成本	改 JSON 原文即可，图自动更新	每加一个字段要补一条箭头
数组处理	自动展开为并列节点	需手工决定摘要还是逐项展开
可控性	结构固定，偏”忠实呈现”	任意布局、任意分组、任意加备注
输出体积	极小，几行数据即可成图	节点多时图会明显变大

选择建议：只是想在 README 或接口文档里贴一份数据快照，用 PlantUML 的 @startjson，最省事；如果要在图上加分组、标注、状态标记，或者数据里只有三个字段，用 Mermaid 流程图更清晰。两者也可以共存——文档里用 Mermaid 讲结构，用 PlantUML 附一份原文快照。

小结

JSON 和 YAML 转图的核心是”数据即结构”。PlantUML 走自动路线，一条指令把原文变成树；Mermaid 走手工路线，用流程图把层级显式画出来。前者适合数据快照与快速留档，后者适合需要解读与标注的正式文档。