name: mermaid-diagrams description: 使用 Mermaid 语法创建软件图表的全面指南。当用户需要通过图表创建、可视化或记录软件时使用，包括类图（领域建模、面向对象设计）、序列图（应用流程、API交互、代码执行）、流程图（过程、算法、用户旅程）、实体关系图（数据库模式）、C4架构图（系统上下文、容器、组件）、状态图、git图、饼图、甘特图或其他任何图表类型。触发词包括请求“图表”、“可视化”、“模型”、“映射出”、“显示流程”，或当解释系统架构、数据库设计、代码结构或用户/应用流程时。

Mermaid 图表制作

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

核心语法结构

所有 Mermaid 图表遵循此模式：

diagramType
  definition content

关键原则：

第一行声明图表类型（例如，classDiagram、sequenceDiagram、flowchart）
使用 %% 进行评论
换行和缩进提高可读性但不是必需的
未知单词会破坏图表；参数无声失败

图表类型选择指南

选择正确的图表类型：

类图 - 领域建模、面向对象设计、实体关系
- 领域驱动设计文档
- 面向对象类结构
- 实体关系和依赖
序列图 - 时间交互、消息流
- API 请求/响应流程
- 用户认证流程
- 系统组件交互
- 方法调用序列
流程图 - 过程、算法、决策树
- 用户旅程和工作流程
- 业务过程
- 算法逻辑
- 部署管道
实体关系图 (ERD) - 数据库模式
- 表关系
- 数据建模
- 模式设计
C4 图 - 多层次软件架构
- 系统上下文（系统和用户）
- 容器（应用、数据库、服务）
- 组件（内部结构）
- 代码（类/接口级别）
状态图 - 状态机、生命周期状态
Git 图 - 版本控制分支策略
甘特图 - 项目时间线、调度
饼图/条形图 - 数据可视化

快速入门示例

类图（领域模型）

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/advanced-features.md - 主题、样式、配置、布局选项

最佳实践

从简单开始 - 从核心实体/组件开始，逐步添加细节
使用有意义的名字 - 清晰的标签使图表自文档化
大量评论 - 使用 %% 评论解释复杂关系
保持专注 - 一个图表一个概念；将大图拆分为多个聚焦视图
版本控制 - 将 .mmd 文件与代码一起存储以便轻松更新
添加上下文 - 包括标题和笔记以解释图表目的
迭代 - 随着理解的演变精炼图表

配置和主题

使用前置数据配置图表：

---
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 中验证语法
过于复杂 - 将复杂图表拆分为多个聚焦视图
缺少关系 - 记录实体之间的所有重要连接

何时创建图表

始终创建图表当：

开始新项目或功能时
记录复杂系统时
解释架构决策时
设计数据库模式时
计划重构工作时
新成员加入团队时

使用图表以：

对齐利益相关者的技术决策
协作记录领域模型
可视化数据流和系统交互
编码前计划
创建与代码一起演化的活文档