从 AI 图表初稿到技术文档：Mermaid 校验、修复与导出实践

AI 生成图表之后，还缺少一次 Review

在编写 README、技术方案和接口文档时，我经常让 AI 根据文字描述生成 Mermaid 图。

例如，我们可以给 AI 这样的需求：

用户提交订单后，请求先经过 API Gateway，再由订单服务检查库存并调用支付服务。库存不足时直接返回失败；支付失败时释放库存；支付成功后创建订单。

AI 通常能很快生成一段 Mermaid 代码。问题是，生成代码只完成了“表达转换”，并不意味着这张图已经可以交付。

实际使用中，经常会遇到几类问题：

• Mermaid 语法无法被当前渲染器解析
• 参与者名称前后不一致
• 只描述正常流程，没有异常分支
• 一条消息承载太多信息，导致图表难以阅读
• 图中的调用关系和真实系统不一致
• 图片可以显示，但源码后续难以维护
• 导出的位图分辨率不足，不适合技术文档

因此，我一般不会直接把 AI 返回的代码复制进文档，而是增加一次“图表 Review”。

第一步：先明确图表需要表达什么

在生成图表之前，需要先限制图表范围。

以订单创建流程为例，这张图只需要回答三个问题：

1. 请求经过哪些服务？
2. 库存不足时如何结束流程？
3. 支付失败后如何进行补偿？

如果同时加入登录鉴权、优惠券、风控、物流和消息通知，图表会迅速变得难以阅读。

一个更适合生成时序图的输入描述是：

参与者包括用户、API Gateway、订单服务、库存服务和支付服务。

流程：
1. 用户向 API Gateway 提交订单。
2. API Gateway 将请求转发给订单服务。
3. 订单服务向库存服务检查并预留库存。
4. 库存不足时返回失败。
5. 库存充足时调用支付服务。
6. 支付失败时释放已预留库存。
7. 支付成功时创建订单并返回订单编号。

这里特意明确了参与者、正常路径和异常路径，可以减少 AI 对业务流程的自由发挥。

第二步：检查 AI 生成的初稿

AI 可能生成类似下面的代码：

sequenceDiagram
    actor User
    participant Gateway
    participant Order
    participant Stock
    participant Payment

    User->>Gateway: Create order
    Gateway->>Order: Forward request
    Order->>Stock: Check stock
    Stock-->>Order: Stock result
    Order->>Payment: Pay
    Payment-->>Order: Payment result
    Order-->>User: Order created

这段代码可以正常渲染，但从业务角度看还不完整。

首先，库存不足时仍然会继续调用支付服务。其次，支付失败后的库存释放没有体现。最后，订单服务直接向用户返回结果，与实际经过 Gateway 返回的调用链不一致。

这也是 AI 图表最容易被忽略的问题：能够渲染，不代表业务关系正确。

第三步：补齐正常流程和异常分支

经过检查后，可以将代码调整为：

sequenceDiagram
    autonumber
    actor U as 用户
    participant G as API Gateway
    participant O as 订单服务
    participant I as 库存服务
    participant P as 支付服务

    U->>G: 提交订单
    G->>O: 创建订单请求
    O->>I: 检查并预留库存

    alt 库存不足
        I-->>O: 预留失败
        O-->>G: 返回库存不足
        G-->>U: 订单创建失败
    else 库存充足
        I-->>O: 预留成功
        O->>P: 发起支付

        alt 支付失败
            P-->>O: 支付失败
            O->>I: 释放预留库存
            I-->>O: 释放完成
            O-->>G: 返回支付失败
            G-->>U: 订单创建失败
        else 支付成功
            P-->>O: 支付成功
            O->>O: 保存订单
            O-->>G: 返回订单编号
            G-->>U: 订单创建成功
        end
    end

这次修改主要解决了四个问题：

• 使用 alt 明确表示不同业务分支
• 补充支付失败后的库存补偿操作
• 保持请求和响应都经过 API Gateway
• 使用统一的参与者别名，避免名称漂移

autonumber 还能给调用步骤自动编号，方便在评审技术方案时引用具体步骤。

第四步：在写入文档前进行实际预览

修改源码后，需要放进真实 Mermaid 渲染器中进行预览。不要只根据代码表面判断，因为不同 Mermaid 版本对部分语法的支持可能存在差异。

我在这个过程中主要检查：

• 是否出现解析错误
• alt 和 else 的层级是否正确
• 参与者是否过多
• 消息文本是否挤压图表
• 中文标签是否完整显示
• 正常路径和失败路径是否容易区分

本文示例使用我整理的 DiagramPreview 页面进行预览。它的作用只是执行渲染和导出，业务关系仍然需要人工检查。

如果图表横向过宽，可以优先缩短消息文本，或者把一个大图拆成“主流程”和“异常处理”两张图。直接缩小字体通常只能暂时掩盖问题。

第五步：选择合适的交付格式

完成检查后，还需要根据使用场景选择输出方式。

README 和代码仓库

如果目标平台支持 Mermaid，建议保留 Mermaid 源码：

这样方便后续通过 Git 修改和审查，也能避免图片与源码失去同步。

技术方案和博客

可以导出 SVG。SVG 在缩放时不会失真，也适合包含较多文字的流程图和时序图。

PNG 更适合不支持 SVG 的平台，但导出时需要检查分辨率，避免在高分辨率屏幕上显示模糊。

AI 图表发布前检查清单

在把图表放入正式文档之前，我通常会进行下面几项检查。

语法检查

• 是否能在目标 Mermaid 版本中正常渲染
• alt、loop、opt 等结构是否正确结束
• 节点名称是否包含需要转义的特殊字符
• 是否使用了目标平台不支持的实验语法

业务检查

• 参与者是否与真实系统一致
• 请求方向和响应方向是否正确
• 是否遗漏失败、超时和重试流程
• 是否存在 AI 自行补充的服务或接口
• 补偿操作是否与主流程对应

可读性检查

• 一张图是否只表达一个核心问题
• 消息标签是否过长
• 是否存在重复或无意义的节点
• 读者能否快速找到入口、结果和异常分支
• 是否需要拆分成多张图

交付检查

• 是否保留可维护的图表源码
• 导出格式是否适合目标平台
• 图片中的文字是否清晰
• 文档内容变化后，图表是否需要同步更新

隐私和安全边界

技术图表经常包含内部服务名称、接口路径、数据库结构和部署关系。使用在线工具或远程 AI 服务时，不应直接提交以下内容：

• AccessKey、Token、密码和证书
• 生产环境域名及内部 IP
• 未公开的系统架构
• 客户数据和业务敏感字段
• 完整的私有仓库代码

比较稳妥的方式是先对服务名、域名和字段进行脱敏，再提交给远程服务。即使工具支持浏览器本地预览，也应确认其中的 AI 修复或生成功能是否会调用远程接口。

总结

AI 可以显著缩短图表初稿的生成时间，但它不能替代发布前检查。

一张真正适合技术文档的图，需要同时满足三个条件：

1. 能够稳定渲染；
2. 业务关系准确；
3. 源码和导出结果便于维护。

更可靠的工作方式不是“让 AI 一次生成最终图”，而是把 AI 当作初稿生成器，再通过预览、业务校验、语法修复和格式选择完成交付。

本文示例使用的预览工具：DiagramPreview。普通预览应尽量在浏览器本地完成；涉及远程 AI 的功能，提交前需要先对内容进行脱敏。

建议发布信息

• 分类：开发工具 / 人工智能 / 前端开发
• 标签：Mermaid、技术文档、生成式 AI、架构设计
• 摘要：AI 生成的 Mermaid 并不一定适合直接写入技术文档。本文通过订单调用流程案例，介绍图表预览、业务校验、异常分支修复和导出交付方法。