mermaid-diagrams

Mermaid 图表绘制

使用 Mermaid 基于文本的语法创建专业的软件图表。Mermaid 可根据简单的文本定义渲染图表，让图表可进行版本控制、易于更新，并能与代码一同维护。

核心语法结构

所有 Mermaid 图表都遵循以下模式：

diagramType
  definition content

核心原则：

• 第一行声明图表类型（例如 classDiagram、sequenceDiagram、flowchart）
• 使用 %% 添加注释
• 换行和缩进能提升可读性，但并非必需
• 未知词汇会导致图表无法正常显示；参数错误会被静默忽略

图表类型选择指南

选择合适的图表类型：

1. 类图 - 领域建模、OOP 设计、实体关系

   • 领域驱动设计文档
   • 面向对象的类结构
   • 实体关系和依赖关系

2. 时序图 - 时序交互、消息流

   • API 请求/响应流程
   • 用户身份验证流程
   • 系统组件交互
   • 方法调用序列

3. 流程图 - 流程、算法、决策树

   • 用户旅程和工作流
   • 业务流程
   • 算法逻辑
   • 部署流水线

4. 实体关系图（ERD） - 数据库架构

   • 表关系
   • 数据建模
   • 架构设计

5. C4 图 - 多层级软件架构

   • 系统上下文（系统和用户）
   • 容器（应用程序、数据库、服务）
   • 组件（内部结构）
   • 代码（类/接口层级）

6. 状态图 - 状态机、生命周期状态

7. Git 图 - 版本控制分支策略

8. 甘特图 - 项目时间线、排期

9. 饼图/柱状图 - 数据可视化

快速入门示例

类图（领域模型）

classDiagram
    Title -- Genre
    Title *-- Season
    Title *-- Review
    User --> Review : creates

    class Title {
        +string name
        +int releaseYear
        +play()
    }

    class Genre {
        +string name
        +getTopTitles()
    }

时序图（API 流程）

sequenceDiagram
    participant User
    participant API
    participant Database

    User->>API: POST /login
    API->>Database: Query credentials
    Database-->>API: Return user data
    alt Valid credentials
        API-->>User: 200 OK + JWT token
    else Invalid credentials
        API-->>User: 401 Unauthorized
    end

流程图（用户旅程）

flowchart TD
    Start([User visits site]) --> Auth{Authenticated?}
    Auth -->|No| Login[Show login page]
    Auth -->|Yes| Dashboard[Show dashboard]
    Login --> Creds[Enter credentials]
    Creds --> Validate{Valid?}
    Validate -->|Yes| Dashboard
    Validate -->|No| Error[Show error]
    Error --> Login

ERD（数据库架构）

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : includes

    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }

    ORDER {
        int id PK
        int user_id FK
        decimal total
        datetime created_at
    }

详细参考

如需了解特定图表类型的深入指南，请参阅：

• references/class-diagrams.md - 领域建模、关系（关联、组合、聚合、继承）、多重性、方法/属性
• references/sequence-diagrams.md - 参与者、消息（同步/异步）、激活、循环、alt/opt/par 块、注释
• references/flowcharts.md - 节点形状、连接、决策逻辑、子图、样式
• references/erd-diagrams.md - 实体、关系、基数、键、属性
• references/c4-diagrams.md - 系统上下文、容器、组件图、边界
• references/architecture-diagrams.md - 云服务、基础设施、CI/CD 部署
• references/advanced-features.md - 主题、样式、配置、布局选项

最佳实践

1. 从简单开始 - 先绘制核心实体/组件，再逐步添加细节
2. 使用有意义的名称 - 清晰的标签能让图表自解释
3. 添加充分注释 - 使用 %% 注释说明复杂关系
4. 保持聚焦 - 每个概念绘制一张图；将大型图表拆分为多个重点明确的视图
5. 版本控制 - 将 .mmd 文件与代码一同存储，便于更新
6. 补充上下文 - 添加标题和注释，说明图表的用途
7. 反复迭代 - 随着理解不断加深，持续完善图表

配置和主题

使用 frontmatter 配置图表：

---
config:
  theme: base
  themeVariables:
    primaryColor: "#ff6b6b"
---
flowchart LR
    A --> B

可用主题： default、forest、dark、neutral、base

布局选项：

• layout: dagre（默认）- 经典的平衡布局
• layout: elk - 适用于复杂图表的高级布局（需要集成）

外观选项：

• look: classic - 传统的 Mermaid 风格
• look: handDrawn - 手绘风格

导出与渲染

原生支持：

• GitHub/GitLab - 在 Markdown 中自动渲染
• VS Code - 配合 Markdown Mermaid 扩展
• Notion、Obsidian、Confluence - 内置支持

导出选项：

• Mermaid Live Editor - 支持 PNG/SVG 导出的在线编辑器
• Mermaid CLI - npm install -g @mermaid-js/mermaid-cli 然后 mmdc -i input.mmd -o output.png
• Docker - docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png

常见陷阱

• 破坏性字符 - 避免在注释中使用 {}，对特殊字符使用正确的转义序列
• 语法错误 - 拼写错误会破坏图表；在 Mermaid Live 中验证语法
• 过度复杂 - 将复杂图表拆分为多个聚焦的视图
• 遗漏关系 - 记录实体之间所有重要的连接

何时创建图表

以下情况务必绘制图表：

• 启动新项目或新功能
• 记录复杂系统
• 解释架构决策
• 设计数据库 schema
• 规划重构工作
• 新团队成员入职

使用图表来：

• 让利益相关者在技术决策上达成一致
• 协作记录领域模型
• 可视化数据流和系统交互
• 在编码前进行规划
• 创建随代码演进的活文档