Comprehensive guide for creating software diagrams using Mermaid syntax. Use when users need to create, visualize, or document software through diagrams including class diagrams (domain modeling, object-oriented design), sequence diagrams (application flows, API interactions, code execution), flowcharts (processes, algorithms, user journeys), entity relationship diagrams (database schemas), C4 architecture diagrams (system context, containers, components), state diagrams, git graphs, pie charts, gantt charts, or any other diagram type. Triggers include requests to "diagram", "visualize", "model", "map out", "show the flow", or when explaining system architecture, database design, code structure, or user/application flows.
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/architecture-diagrams.md - 云服务、基础设施、CI/CD 部署
- references/advanced-features.md - 主题、样式、配置、布局选项
最佳实践
- 从简单开始 - 从核心实体/组件开始，逐步添加细节
- 使用有意义的名称 - 清晰的标签使图表自文档化
- 大量注释 - 使用
%%注释解释复杂关系 - 保持专注 - 每个概念一个图表；将大型图表拆分为多个聚焦视图
- 版本控制 - 将
.mmd文件与代码一起存储，便于更新 - 添加上下文 - 包含标题和注释以解释图表目的
- 迭代 - 随着理解的深入不断完善图表
配置与主题
使用 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 中验证语法
- 过度复杂 - 将复杂图表拆分为多个聚焦视图
- 遗漏关系 - 记录实体之间的所有重要连接
何时创建图表
在以下情况始终创建图表：
- 开始新项目或功能时
- 记录复杂系统时
- 解释架构决策时
- 设计数据库模式时
- 规划重构工作时
- 新团队成员入职时
使用图表的目的：
- 在技术决策上对齐利益相关者
- 协作记录领域模型
- 可视化数据流和系统交互
- 编码前进行规划
- 创建随代码演进的活文档
