mermaid-builder

Mermaid 构建器

核心理念

• 正确性：严格遵循 Mermaid 语法规则
• 清晰性：用图表简单地传达复杂概念
• 简洁性：避免加入不必要的细节
• 模块化：将复杂图表拆分为子图

重要：标签加引号规则

规则：如果标签包含空格、特殊字符或标点符号，请用双引号括起来。

%% CORRECT - labels with spaces quoted
flowchart LR
    A["User Login"] --> B["Process Request"]
    C["Pay $100?"] --> D["Confirm (Yes/No)"]

%% WRONG - will fail to render
flowchart LR
    A[User Login] --> B[Process Request]

**必须加引号：**空格、特殊字符（$%&）、标点符号（:,;）、运算符（()[]） **可选：**简单的字母数字组合（Login、Process、Node1）

不确定时就加引号。这样做不会有坏处。

快速参考

流程图形状

语法	形状
["Text"]	矩形
("Text")	圆角矩形
{"Text"}	菱形（决策）
[("Text")]	圆柱体（数据库）
(("Text"))	圆形

箭头类型

语法	类型
-->	实线箭头
---	实线
-.->	虚线箭头
==>	粗箭头
`-->	Label

图表类型

类型	声明	用途
流程图	flowchart TD	流程、工作流、决策
时序图	sequenceDiagram	组件交互、API 流程
类图	classDiagram	面向对象结构、模型
状态图	stateDiagram-v2	状态转换
甘特图	gantt	时间线、排期
ER 图	erDiagram	数据库架构
饼图	pie	比例数据

方向：TB/TD（自上而下）、BT（自下而上）、LR（从左到右）、RL（从右到左）

各类图表的完整示例请参阅 references/diagram-examples.md。

最简示例

流程图

flowchart TD
    Start["Start"] --> Check{Valid?}
    Check -->|Yes| Process["Process"]
    Check -->|No| Error["Error"]
    Process --> End["End"]

时序图

sequenceDiagram
    Client->>Server: Request
    Server-->>Client: Response

ER 图

erDiagram
    USER ||--o{ ORDER : "places"
    USER { int id PK string email }
    ORDER { int id PK int user_id FK }

使用子图进行组织

flowchart TD
    subgraph "Frontend"
        A["UI"]
    end
    subgraph "Backend"
        B["API"]
        C[("DB")]
    end
    A --> B --> C

样式

flowchart TD
    A["Success"] --> B["Error"]

    classDef successStyle fill:#C8E6C9,stroke:#388E3C
    classDef errorStyle fill:#FFCDD2,stroke:#D32F2F

    class A successStyle
    class B errorStyle

应避免的常见错误

错误	错误写法	正确写法
未给空格加引号	A[User Login]	A["User Login"]
箭头无效	A -> B	A --> B
未给特殊字符加引号	A[Cost: $100]	A["Cost: $100"]
缺少括号	A["Node --> B	A["Node"] --> B

验证清单

• 含空格的标签已加引号
• 含特殊字符的标签已加引号
• 括号匹配正确
• 箭头语法正确（--> 而非 ->）
• 节点 ID 唯一且有意义
• 注释说明了复杂部分
• 已预览且无错误

数据血缘模式

请参阅 references/data-lineage.md，了解：

• ETL 流水线模式
• 多层数据架构
• 跨系统数据流
• 数据库架构血缘
• 流式数据血缘
• 列级血缘

资源

• Mermaid 文档
• 在线编辑器
• 语法参考

---

请记住：标签加引号规则是导致 Mermaid 渲染失败的首要原因。不确定时就加引号。