Mermaid 图表即代码: 用文本写架构图和流程图

# Mermaid 图表即代码: 用文本写架构图和流程图 ## 为什么用图表即代码 传统画图工具（Visio、draw.io）的问题： - 二进制文件无法 diff 和 code review - 版本管理困难 - 修改门槛高（要打开专用软件） Mermaid 用纯文本描述图表，直接嵌入 Markdown，GitHub/GitLab 原生渲染。 ## 流程图 (Flowchart) ``` graph TD A[用户请求] --> B{是否登录?} B -->|是| C[鉴权检查] B -->|否| D[跳转登录页] C --> E{权限是否足够?} E -->|是| F[处理请求] E -->|否| G[返回 403] F --> H[返回结果] D --> I[登录成功] --> C ``` 方向控制： - `TD` / `TB`：从上到下 - `LR`：从左到右 - `RL`：从右到左 - `BT`：从下到上 节点形状： - `[矩形]`、`(圆角矩形)`、`{菱形}` - `([体育场形])`、`[[子程序]]`、`[(圆柱形)]` - `((圆形))`、`>不对称]` ## 序列图 (Sequence Diagram) ``` sequenceDiagram participant C as Client participant G as API Gateway participant A as Auth Service participant S as Order Service participant D as Database C->>G: POST /api/orders G->>A: 验证 JWT Token A-->>G: Token 有效 G->>S: 转发请求 S->>D: INSERT order D-->>S: order_id=1001 S-->>G: 201 Created G-->>C: { id: 1001 } Note over S,D: 事务边界 rect rgb(255, 240, 240) S->>D: UPDATE inventory D-->>S: OK end ``` 箭头类型： - `->>` 实线箭头 - `-->>` 虚线箭头 - `-x` 末端叉号 - `-)` 异步消息 ## 类图 (Class Diagram) ``` classDiagram class Order { -Long id -String orderNo -BigDecimal amount -OrderStatus status +create() Order +cancel() void +complete() void } class OrderItem { -Long id -Long orderId -String productName -Integer quantity -BigDecimal price } class Payment { -Long id -Long orderId -PaymentMethod method -BigDecimal amount +process() PaymentResult +refund() void } Order "1" --> "*" OrderItem : contains Order "1" --> "0..1" Payment : has Order ..> OrderStatus : uses ``` ## ER 图 (Entity Relationship) ``` erDiagram USER ||--o{ ORDER : places ORDER ||--|{ ORDER_ITEM : contains ORDER ||--o| PAYMENT : has PRODUCT ||--o{ ORDER_ITEM : "ordered in" USER { bigint id PK varchar username UK varchar email timestamp created_at } ORDER { bigint id PK bigint user_id FK varchar order_no UK decimal amount enum status } ``` 关系符号： - `||` 恰好一个 - `o|` 零或一个 - `|{` 一个或多个 - `o{` 零或多个 ## 甘特图 (Gantt Chart) ``` gantt title 项目开发计划 dateFormat YYYY-MM-DD axisFormat %m/%d section 后端 API 设计 :a1, 2024-01-01, 5d 数据库设计 :a2, after a1, 3d 核心接口开发 :a3, after a2, 10d 接口测试 :a4, after a3, 5d section 前端 UI 设计 :b1, 2024-01-01, 7d 组件开发 :b2, after b1, 8d 页面集成 :b3, after b2, 7d E2E 测试 :b4, after b3, 3d section 部署 CI/CD 搭建 :c1, 2024-01-08, 3d 灰度发布 :c2, after a4, 2d 正式上线 :milestone, after c2, 0d ``` ## 状态图 (State Diagram) ``` stateDiagram-v2 [*] --> Draft Draft --> Submitted : 用户提交 Submitted --> Reviewing : 分配审核人 Reviewing --> Approved : 审核通过 Reviewing --> Rejected : 审核拒绝 Rejected --> Draft : 修改后重提 Approved --> Published : 发布 Published --> [*] state Reviewing { [*] --> ContentCheck ContentCheck --> TechCheck : 内容合格 ContentCheck --> NeedRevision : 内容不合格 TechCheck --> [*] : 技术合格 } ``` ## 在文档中使用 GitHub 和 GitLab 原生支持 Mermaid 代码块： ````markdown ## 系统架构 ```mermaid graph LR A[Web App] --> B[API Gateway] B --> C[Auth Service] B --> D[Order Service] B --> E[Product Service] C --> F[(User DB)] D --> G[(Order DB)] E --> H[(Product DB)] ``` ```` ## CI 中生成图片 ```yaml # .github/workflows/docs.yml - name: Generate diagrams uses: mermaid-js/mermaid-cli-action@v1 with: input: docs/diagrams/ output: docs/images/ format: svg ``` ## VS Code 插件 - **Markdown Preview Mermaid Support**：预览中渲染 Mermaid - **Mermaid Markdown Syntax Highlighting**：语法高亮 ## 最佳实践 1. **图表文件单独存放**：`docs/diagrams/` 目录 2. **保持简洁**：一张图不超过 15 个节点 3. **添加注释**：用 `%%` 在 Mermaid 中写注释 4. **配合 ADR**：每个架构决策附带图表 ## 总结 Mermaid 让图表成为代码的一部分，可以 diff、review、版本控制。掌握流程图和序列图就能覆盖 80% 的文档图表需求。在 GitHub/GitLab 中原生渲染，零额外成本。