规格片段#

Archify 的 sequence 图规格就是「参与者 + 消息 + 激活条」三张表，语义字段全是人话：

1
{
2
  "diagram_type": "sequence",
3
  "participants": [
4
    { "id": "api",   "type": "backend",  "label": "API 服务",  "sublabel": "请求处理层" },
5
    { "id": "redis", "type": "database", "label": "Redis",     "sublabel": "缓存层" },
6
    { "id": "db",    "type": "database", "label": "PostgreSQL","sublabel": "权威数据源" }
7
  ],
8
  "messages": [
9
    { "id": "cache-read", "from": "api", "to": "redis", "y": 209,
10
      "label": "GET cache:{key}", "variant": "default" },
11
    { "id": "cache-miss", "from": "redis", "to": "api", "y": 248,
12
      "label": "nil（未命中）", "variant": "return" },
13
    { "id": "db-query", "from": "api", "to": "db", "y": 287,
14
      "label": "SELECT ... WHERE id = ?", "variant": "emphasis" },
15
    { "id": "cache-write", "from": "api", "to": "redis", "y": 365,
16
      "label": "SET cache:{key} EX 300", "variant": "dashed" }
17
  ]
18
}

variant 是有语义的：emphasis 是主路径、return 是返回（视觉更弱）、dashed 是异步/非阻塞副作用、security 是安全交互。不用手写颜色——颜色由 variant 决定，明暗主题自动适配。

布局踩坑（这部分是真实代价）#

Archify 的校验器很严格，我这三处都被打回过：

1. 不支持自消息。我原本加了个 api → api 的「序列化为缓存值」节点，报错 spans 0px (minimum 60px)。序列化成缓存值是实现细节，本来就该并进回填那条消息的 note 里；
2. 消息 y 间距至少 28px。我压缩布局时把间距压到 24px，直接被判 share horizontal space；
3. viewBox 加宽会让文字缩到不可读。为了填满 2048 大屏我把 viewBox 从 1080 加宽到 1400，结果 1440×900 视口下缩放比只有 0.66，参与者副标题投影后 4.65px，低于 6px 下限被判 desktop-readability 失败。

第三条值得展开：viewBox 宽度不是「画布越大越好」，它直接决定了小屏上的缩放比。加大 viewBox 只能同比加高（保持宽高比），不能单边加宽；真正该做的是把内容在时间轴上铺得更均匀——我最后把 8 条消息从挤在 258px 改成等距铺满 273px，面板纵向饱满度上来了，宽度保持 1080 不动。

校验命令与通过标准：

1
node bin/archify.mjs validate sequence cache-miss-flow.sequence.json --quality showcase --json
2
# ok:true / composition pass / errors:0 / warnings:0 / 9 项 artifact checks 全绿

为什么这张也画成时序图，而不是架构图#

我第一版确实画的是 architecture（组件 + 边界 + 连线），校验器直接判死：

1
[clean-flow/edge-through-node]   A -> 对象存储 crosses component "主库"
2
[composition/proper-crossing]    网关 -> 用户服务 crosses 网关 -> Redis
3
[composition/ambiguous-corridor] 两条边共用 60px 通道
4
[composition/micro-segment]      B -> Kafka 出现 7px 内部线段

在 3×4 的组件网格里，网关既要连上面的 Redis、用户服务、配置中心，又要连右边的业务服务——长连线必然穿过中间节点。这不是我不会摆位置，是这类拓扑在网格布局下的固有问题。（上面的组件名已改为通用称呼，错误码是校验器的原样输出。）

改画时序图之后，同样的信息变成了纵向时间轴，天然没有交叉。而且顺序本身就是信息：「鉴权 → 权限回源 → 转发 → 落库 → 异步通知」是一条线，架构图上这些箭头是散的。

选型的经验是：**想表达「谁调用谁、系统里有什么」用 architecture；想表达「一次请求怎么流转、先后顺序是什么」用 sequence。**用户问的是「请求流程」，那答案就是 sequence。

布局踩坑（第二张）#

1. 时间轴有硬边界。12 条消息最后一条排在 y=483，被判 sits outside the readable timeline — keep y between 160 and 477。viewBox 高度决定了可用时间轴范围，超了就得压缩间距或增高画布；
2. 说明卡片会把页面撑到滚动。我的三张卡片每条写了 50-70 字，在 1440×900 视口下总高度 944px（超 44px）。把每条压到 38 字以内、回到第一张图的密度，恰好 900px 无滚动。卡片文字长度是布局变量，不是文案变量——这是最容易忽略的一条。