如何用 Mermaid 泳道图（swimlane-beta）表达跨团队流程中的职责与交接

如果你要画一个横跨多个团队、系统或阶段的流程，普通流程图只能回答“下一步做什么”，回答不了“这一步归谁管、交接在什么条件下发生”。Mermaid 从 v11.16.0 起新增了泳道图（swimlanes diagram），用 swimlane-beta 关键词声明，每条泳道（lane）代表一个责任人、团队、系统或阶段，泳道内的节点表示发生在那里的工作，跨泳道的箭头表示工作顺序和职责交接。这篇文章说明如何用泳道图把一个跨团队流程的职责归属和交接条件完整表达出来，以及如何验证渲染结果。

前提只有一个：使用的 Mermaid 版本为 v11.16.0 或更高（泳道图在该版本引入，且目前仍处于 beta 状态，文档明确提示其语法可能在后续版本中演进）。完整语法参考见 泳道图语法文档，该文件是自动生成文档，源文件位于 swimlanes.md。

判断你的流程是否适合泳道图

文档给出的判断标准是：如果最重要的问题不只是“下一步做什么”，还有“这一步归谁管”，就适合泳道图，典型场景包括审批流、支持流程、交付工作流，以及任何工作会跨团队或跨系统的流程。

以下情况应改用其他图表，避免画出来却答非所问：

• 只关心顺序和分支、不关心归属：用普通 flowchart；
• 重点是参与者之间随时间传递的消息：用 sequence diagram；
• 重点是单个对象的状态变化：用 state diagram。

第一步：声明图表类型与方向

泳道图以 swimlane-beta 关键词开头，后面可以跟一个可选的布局方向：

swimlane-beta

swimlane-beta LR

支持的方向如下：

Direction	Meaning
TB	Top to bottom
TD	Top down, same as TB
BT	Bottom to top
LR	Left to right
RL	Right to left

不写方向时默认为 TB。文档中的示例普遍使用 LR，即每条泳道从左到右展开、跨泳道交接横向发生，适合横向阅读“谁在哪个阶段接棒”的跨团队流程。

第二步：用 subgraph 划出泳道，把步骤放进对应团队

在泳道图中，顶层的 subgraph 会被渲染为一条泳道，以 end 结束。先把流程里的每个步骤按“由谁负责”归类，再逐个写入对应泳道：

swimlane-beta LR
  subgraph Customer
    request[Request service]
    receive[Receive update]
  end

  subgraph Support
    triage[Triage request]
    answer[Send answer]
  end

  subgraph Engineering
    investigate[Investigate issue]
    fix[Prepare fix]
  end

  request --> triage
  triage -->|Known issue| answer
  triage -->|Needs code change| investigate
  investigate --> fix --> answer
  answer --> receive

这是文档给出的基础示例：客服请求先由客户提出，Support 分诊后要么直接答复，要么交给 Engineering 排查修复，最后答复回传客户。每个节点的归属泳道就是它的责任方。

如果泳道名包含空格，或需要为泳道准备一个稳定的 id 用于后续样式引用，可以写成“内部 id + 显示标签”的形式：

swimlane-beta LR
  subgraph sales [Sales team]
    lead[Qualify lead]
    quote[Prepare quote]
  end

  subgraph finance [Finance team]
    review[Review terms]
    approve[Approve quote]
  end

  lead --> quote --> review --> approve

节点使用 flowchart 风格写法：先写 id，标签写在形状内。文档列出的常用节点形式：

Syntax	Shape	Common use
id[Text]	Rectangle	Task or activity
id(Text)	Rounded rectangle	Step or event
id([Text])	Stadium	Start or end
id{Text}	Decision	Branching question
id((Text))	Circle	Connector or marker

完整形状目录（图标、图片、markdown 字符串、class 与样式选项）见 flowchart 语法文档。

第三步：用带标签的跨泳道箭头表达交接

跨泳道的箭头就是职责发生变化的位置。文档的建议是：当交接依赖某个文档、决策、消息或条件时，必须给这条箭头加标签，否则读者看不到交接的触发条件。

swimlane-beta LR
  subgraph Applicant
    apply[Submit application]
    sign[Sign agreement]
  end

  subgraph Reviewer
    screen[Screen application]
    decide{Approved?}
  end

  subgraph System
    create[Create account]
    notify[Send welcome email]
  end

  apply -->|Application received| screen
  screen --> decide
  decide -->|Approved| create --> notify --> sign
  decide -->|Needs changes| apply

这个示例里三次跨泳道交接都带标签：|Application received| 说明申请材料如何从 Applicant 流到 Reviewer，|Approved| 与 |Needs changes| 说明审核决策的两个分支分别流向 System 和退回 Applicant。

文档列出的常用边形式（同样来自 flowchart 语法，支持同泳道内和跨泳道连接）：

Syntax	Meaning
A --> B	Arrow
A --- B	Line without arrowhead
`A -->	Label
A -.-> B	Dotted arrow
A ==> B	Thick arrow

多向箭头、最小连线长度等完整边语法见 flowchart 文档的 links 章节。

第四步：让泳道划分和决策位置符合文档给出的实践

文档的 Good Practices 部分给出了四条可直接执行的规则，每条都对应一个容易画错的点：

1. 每条泳道只表达一种归属。泳道要能回答“这一步归谁管”，不要把团队、阶段、状态混在同一条泳道里，除非这种混用本身就是图要表达的重点。
2. 给跨泳道交接加标签，即上一条的做法。
3. 决策节点放在做出决策的泳道里，再把它两个（或多个）结果路由到执行后续动作的泳道。例如：

swimlane-beta LR
  subgraph Support
    classify{Can support solve it?}
    respond[Respond to customer]
  end

  subgraph Product
    prioritize[Prioritize fix]
  end

  subgraph Engineering
    implement[Implement fix]
  end

  classify -->|Yes| respond
  classify -->|No| prioritize --> implement --> respond

这里 classify 属于 Support，因为它判断的就是 Support 能否直接解决；“解决不了”的分支再路由到 Product 和 Engineering 的行动。

4. 使用短而有意义的稳定 id。标签可以改，但边、样式和后续引用依赖 id 不变。泳道同样适用，例如：

swimlane-beta LR
  subgraph ops [Operations]
    intake[Receive request]
    plan[Plan work]
  end

  subgraph legal [Legal]
    review[Review contract]
  end

  intake --> plan --> review

  classDef attention fill:#fff2cc,stroke:#d6a500,color:#111;
  class review attention;

例子里用 classDef/class 给法务审查节点加了高亮——泳道图支持 flowchart 的样式语句，用稳定 id 才能在改标签后样式不失效。

如果流程太长，文档的取舍标准是：当泳道和交接“装不进一个视图”时，把大流程拆成几张图，而不是一张图硬塞所有节点。

可选：为泳道图补充可访问性信息

泳道图支持 accTitle 和 accDescr 两条声明，用来提供可访问的标题和描述：

swimlane-beta LR
  accTitle: Support escalation
  accDescr: A request starts with the customer, is triaged by support, and may be escalated to engineering.

  subgraph Customer
    request[Open request]
  end

  subgraph Support
    triage[Triage]
  end

  subgraph Engineering
    resolve[Resolve]
  end

  request --> triage --> resolve

跨团队流程往往会分发给不同角色阅读，给出标题与描述能让屏幕阅读器使用者理解图的用途，建议随图一并写出。

渲染与结果验证

把上面的 mermaid 代码块放进任何支持 Mermaid 的渲染环境（Mermaid 版本需 ≥ v11.16.0）即可。默认情况下泳道图使用你配置的默认 look 和 theme（文档页面上的示例使用的是 Neo look 与 Redux 主题，这只是展示选择，不是默认值）。

项目自带的 e2e 测试（swimlanes.spec.ts）展示了如何判断一张泳道图是否渲染成功，可以在浏览器或自动化环境中照做：

• 渲染出的 svg 根元素带有 aria-roledescription="swimlane"；
• 每个泳道对应一个 g.cluster.swimlane 组，泳道数量与 subgraph 数量一致；
• 页面中不存在 .error-icon（无语法/渲染错误）；
• 节点以 g.node（handdrawn 风格下为 g.rough-node）形式存在且文本可见。

该测试还确认了两个值得注意的行为：

• 支持通过 themeVariables 覆盖 mainBkg（节点背景）、nodeBorder（节点边框）、lineColor（连线颜色）等主题变量；
• style、linkStyle、classDef、class 语句均可生效；
• 没有写进任何 subgraph 的节点不会报错，而是被放入一个默认泳道（内部 id 为 __swimlane_default__）。写图时如果某个节点意外出现在默认泳道里，说明它漏写了归属的 subgraph——这正是跨团队流程中“这一步归谁管”答错的地方，需要回改归属。

限制与边界

• 泳道图是 v11.16.0 引入的新图表类型，官方文档明确标注“its syntax may evolve in future versions”，依赖该语法的模板或自动化生成建议在升级 Mermaid 时重新核对渲染结果。
• 节点形状、边类型、样式与主题均沿用 flowchart 体系，flowchart 侧的变更会直接影响泳道图。
• 文档未提供泳道专用的独立配置项（如泳道间距、泳道顺序控制），布局方向由开头的 TB/TD/BT/LR/RL 决定。

下一步可以沿着 flowchart 语法文档 补全图标、markdown 字符串等节点高级用法，或用 theme 配置文档 统一泳道图与公司文档的主题。