Excalidraw 架构图(EIP 符号) 是做什么的?
一个图就是一个小型的 JSON 规范 —— 节点、边、分组 —— 外加一个生成器,它会按 Hohpe & Woolf 符号进行布局。规范是事实的来源;.excalidraw 文件和预览 .svg 是构建产物。
下面的 <skill-dir> 是此技能安装的目录 —— 例如 ~/.omp/agent/skills/excalidraw-architecture、~/.claude/skills/excalidraw-architecture 或 .agents/skills/excalidraw-architecture —— 以及在 https://github.com/jamescarr/diagram-skill 仓库中的 skills/excalidraw-architecture。
何时使用
- 被要求绘制、描画、草图或可视化一个服务、事件或消息架构时。
- 解释消息如何传输:使用哪个频道、哪个端点、失败时会发生什么。
- 在上下文、流程或端点级别记录一个限界上下文的集成面。
- 审查消息导向的设计时,需要让图表暴露缺少的死信队列、关联标识符或幂等性。
不要使用
- UI 线框图、线框、幻灯片、自由画板。
- 单个进程内的调用顺序图。
- 交付物不是
.excalidraw文件的任何内容。
工作流程
-
清点 —— 在绘图前列出:
- 参与者:服务、外部系统、执行者、数据存储;
- 频道:名称、点对点 vs 发布-订阅、键/分区/排序、持久性、死信队列;
- 消息:名称(命令 = 祈使句、事件 = 过去时、文档 = 名词)和类型;
- 每个服务的端点:网关、出箱/事务、消费者风格、竞争数量、幂等性、持久性、选择性;
- 路由和转换步骤;
- 请求-回复对:回复频道、关联、TTL;
- 管理:线路检测、存储、控制总线。
如果对模式选择不明确,请阅读
enterprise-integration-patterns技能(如果已安装)。
-
选择级别 ——
context:执行者、服务、外部系统、代理作为message-bus、rpc/data边。flow(默认):一个端到端的业务流程,包含频道和 EIP 组件。endpoint:一个服务内部 —— 网关 → 出箱 → 频道,或消费者 → 幂等接收器 → 激活器。每个图只针对一个流程,最多 20 个节点;超过则按流程拆分。 -
编写规范 ——
<name>.spec.json放在图表所在目录旁(默认docs/architecture/),参考下面的速查表。运行node <skill-dir>/scripts/eip_excalidraw.mjs kinds查看实时分类。 -
构建 ——
node <skill-dir>/scripts/eip_excalidraw.mjs build <name>.spec.json会生成<name>.excalidraw和<name>.svg。修复每个error:(退出码 2);将warning:视为布局缺陷(--strict会使警告以退出码 1 退出)。--check仅验证布局而不写入文件。 添加--png [OUT.png]可以额外导出由 Excalidraw 本身渲染的 PNG(手绘风格、Excalifont 字体、场景嵌入文件中以便重新拖放回 excalidraw.com)—— 这是 README、文档或博客文章应嵌入的格式。它需要 Chrome 或 Chromium(CHROME可覆盖查找路径)以及访问 esm.sh 的网络能力;通过scripts/export_png.mjs驱动浏览器。导出失败时退出码为 3,但场景仍会写入。 -
查看 —— 如果构建了 PNG 则
read <name>.png,否则read <name>.svg:img;然后对照审查清单。 -
修复 —— 每次规范更改后重新构建:
症状 规范修改 箭头穿过节点 设置 route: "ortho"或"below",或固定row标签与节点重叠 缩短 message/label,或通过固定row将节点移开箭头箭头缩小 该列间距中箭头过多:将箭头路由到 below/above,或固定row使较少竖线共享该列向后箭头混乱 route: "above"回复箭头在整个图表下循环 route: "ortho",或将回复频道放在请求频道旁边列拥挤 添加 lanes,或拆分图表长节点标签 将细节移到 sub组成员分散 固定 col/row使成员相邻框包含非成员 固定 col/row或使用lanes使组的成员形成连续块 -
交付 ——
.spec.json、.excalidraw和.svg(如果构建了 PNG,还包括.png)。说明规范是事实来源:编辑后重新生成。之后可以直接在 Excalidraw 中手动编辑,但重新构建会覆盖它们。
建模规则
每条规则都是图表必须能展示的主张;如果无法成立,则必须明确绘制例外情况。
- 每个频道显示其种类标签和键/分区/排序标签(
tags)。 - 每个消费至少一次频道的消费者都带有
idempotent—— 或者图表说明为什么不。徽章只存在于应用族节点上,因此 Saga、路由器或聚合器在sub中说明其去重规则(dedupe by orderId)。 - 每个消费者可能失败的频道都有一个
dead-letter-channelshadow;验证失败则获得invalid-message-channel。未绘制或故意缺失的死信队列,需在频道的sub或note中说明。 - 请求-回复 = 一条命令边,带有
reply_to和correlation,再加上一条虚线回复返回边。 - 聚合器、散布-收集和 Saga 节点在
sub中带有完成规则(计数/超时)。 - 事务内的发布 = 一个
outbox徽章或outbox节点,绝不能是提交后的裸发布。 - 转换器位于限界上下文边界(框)上。
- 竞争型消费者显示
competing:N;持久订阅带有durable。 - 线路检测是通往
message-store的tap边。 - 智能端点,哑管道:路由逻辑位于路由器节点中,绝不能隐含在频道内部。
- 同步调用是
rpc边,且是例外而非默认。 - 跨越边界的内部记录需要一个
content-filter,或一个claim-check引用。
规范速查表
按 EIP 章节分类的节点 —— 完整的种类对照表在 references/spec.md:
| 章节 | 种类 | 使用场景 |
|---|---|---|
| 频道 | channel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-bus | 消息在参与者之间移动;选择点对点 vs 发布-订阅,然后是失败频道。 |
| 消息 | message command-message document-message event-message | 消息本身是主题,而不是端点。 |
| 路由 | content-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager saga | 一条消息有多个可能的目标,或需要重新组合部分。 |
| 转换 | message-translator envelope-wrapper content-enricher content-filter claim-check normalizer | 在跳转之间,有效载荷或其信封发生变化。 |
| 端点 | message-endpoint messaging-gateway messaging-mapper transactional-client polling-consumer event-driven-consumer competing-consumers message-dispatcher selective-consumer durable-subscriber idempotent-receiver service-activator channel-adapter | 服务如何连接到频道并消费它。 |
| 系统管理 | wire-tap detour message-history smart-proxy test-message channel-purger | 可观测性、探测和运维。 |
| 基础设施 | message-broker messaging-bridge outbox inbox | 代理本身、代理间链接、事务性发布/消费。 |
| 参与者和存储 | service external-system actor datastore message-store schema-registry note | 谁拥有频道末端;状态、模式和注释的存储位置。 |
徽章(仅应用族节点;药丸形状渲染简短文本):
| 分组 | 徽章 |
|---|---|
| 端点 | gateway(消息网关)、mapper(消息映射器)、activator(服务激活器)、adapter(通道适配器) |
| 消费 | polling(轮询消费者)、event-driven(事件驱动消费者)、competing / competing:N(竞争消费者,在最多三个盒子的堆栈上渲染 competing ×N)、dispatcher(消息调度器)、selective(选择性消费者)、durable(持久订阅者) |
| 事务 | tx(事务客户端)、outbox(事务性出箱)、inbox(事务性收件箱)、idempotent(幂等接收器) |
| 弹性 | bulkhead、retry、circuit-breaker —— 弹性模式,非 EIP |
边:
| 边类型 | 线条样式 | 宽度 | 箭头 | 标记 |
|---|---|---|---|---|
message(无类型) | 实线 #1e1e1e | 2 | → arrow | 无 |
message type: command | 实线 | 2 | → triangle | «C» |
message type: event | 实线 | 2 | → arrow | «E» |
message type: document | 实线 | 2 | → arrow | «D» |
message type: reply | 虚线 | 2 | → arrow | «R» |
rpc | 实线 | 1 | → arrow | 无 |
data | 点线 | 1 | → arrow | 无 |
tap | 点线 | 1 | circle → arrow | 无 |
dlq | 虚线 #c92a2a | 1 | → arrow | 无 |
control | 虚线 #868e96 | 1 | ┤ bar | 无 |
边字段:from、to、kind、type、message、label、seq、route、correlation、reply_to、ttl、sequence、style、color。节点字段:id、kind、label、sub、badges、tags、group、lane、col、row、shadow、attach、link。
审查清单
- 标题存在;它命名的是流程,而不是整个系统。
- 每条箭头都标记了消息或调用。
- 每个频道都带有其种类标签和键/分区标签。
- 每个频道的死信队列决定可见。
- 当超过 6 种种类出现时,存在图例。
- 没有构建过程中留下的
warning:。 - 分组框只包含其成员。
- 最多 20 个节点。
技术栈映射
| 技术栈 | 绘制为 |
|---|---|
| Kafka topic | pubsub-channel;消费者组 → competing:N;持久订阅 → durable |
| RabbitMQ queue | p2p-channel;exchange → message-broker 或 content-based-router;DLX → dead-letter-channel |
| SQS / SNS | p2p-channel / pubsub-channel |
| EventBridge rule | content-based-router |
| Step Functions | process-manager 或 saga |
| Lambda consumer | service 带有 event-driven |
| 数据库 | datastore;审计/重放副本 → message-store |
| 合作伙伴 API | external-system,虚线 |
手动编辑
references/excalidraw-format.md 列出了 JSON 不变性约束,以保持手动编辑后 Excalidraw 的绑定、文本和框的有效性。