图表绘制
概述
使用 Mermaid 语法创建清晰、可维护的技术图表。本技能涵盖用于记录软件系统的架构图、时序图、实体关系图、流程图和状态图。
指导说明
1. 选择合适的图表类型
| 图表类型 | 适用场景 |
|---|---|
| 架构图/C4 | 展示系统结构和组件 |
| 时序图 | 展示随时间推移的交互 |
| ERD | 展示数据模型和关系 |
| 流程图 | 展示决策逻辑和流程 |
| 状态图 | 展示状态转换 |
2. 通用 Mermaid 原则
- 保持图表聚焦于单一概念
- 使用一致的命名约定
- 为关系添加描述性标签
- 限制复杂度（拆分大型图表）
- 使用注释进行文档化
最佳实践
- 简洁：一图一概念
- 一致：相关图表间使用相同命名
- 可读性：从左到右或从上到下的流程
- 标签：始终标注关系和转换
- 上下文：包含标题和简短描述
示例
架构图（C4 模型）
上下文图（第 1 层）
C4Context
title 电商平台系统上下文图
Person(customer, "顾客", "购买产品的用户")
Person(admin, "管理员", "管理产品和订单")
System(ecommerce, "电商平台", "允许顾客浏览和购买产品")
System_Ext(payment, "支付网关", "处理支付")
System_Ext(shipping, "物流供应商", "处理订单履约")
System_Ext(email, "邮件服务", "发送通知")
Rel(customer, ecommerce, "浏览、购买")
Rel(admin, ecommerce, "管理")
Rel(ecommerce, payment, "处理支付")
Rel(ecommerce, shipping, "创建物流单")
Rel(ecommerce, email, "发送邮件")
容器图（第 2 层）
C4Container
title 电商平台容器图
Person(customer, "顾客")
Container_Boundary(ecommerce, "电商平台") {
Container(web, "Web 应用", "React", "面向顾客的前端 UI")
Container(api, "API 网关", "Node.js", "REST API")
Container(cart, "购物车服务", "Node.js", "购物车管理")
Container(catalog, "目录服务", "Python", "产品目录")
Container(order, "订单服务", "Java", "订单处理")
ContainerDb(db, "数据库", "PostgreSQL", "存储所有数据")
ContainerQueue(queue, "消息队列", "RabbitMQ", "异步消息")
}
Rel(customer, web, "使用", "HTTPS")
Rel(web, api, "调用", "JSON/HTTPS")
Rel(api, cart, "路由到")
Rel(api, catalog, "路由到")
Rel(api, order, "路由到")
Rel(cart, db, "读写")
Rel(catalog, db, "读取")
Rel(order, db, "读写")
Rel(order, queue, "发布事件")
组件图（第 3 层）
flowchart TB
subgraph "订单服务"
controller[订单控制器]
service[订单服务]
repo[订单仓库]
validator[订单验证器]
publisher[事件发布器]
end
subgraph "外部"
db[(PostgreSQL)]
queue[RabbitMQ]
end
controller --> service
service --> validator
service --> repo
service --> publisher
repo --> db
publisher --> queue
时序图
基本请求流程
sequenceDiagram
autonumber
participant C as 客户端
participant G as API 网关
participant A as 认证服务
participant S as 服务
participant D as 数据库
C->>G: POST /api/resource
G->>A: 验证令牌
A-->>G: 令牌有效
G->>S: 转发请求
S->>D: 查询数据
D-->>S: 返回结果
S-->>G: 响应 (200 OK)
G-->>C: 返回数据
错误处理流程
sequenceDiagram
participant C as 客户端
participant S as 服务
participant D as 数据库
C->>S: POST /api/users
S->>S: 验证输入
alt 验证失败
S-->>C: 400 错误请求
else 验证通过
S->>D: INSERT user
alt 数据库错误
D-->>S: 约束违反
S-->>C: 409 冲突
else 成功
D-->>S: 用户创建成功
S-->>C: 201 已创建
end
end
异步处理
sequenceDiagram
participant C as 客户端
participant API as API
participant Q as 队列
participant W as 工作者
participant N as 通知
C->>API: 提交作业
API->>Q: 入队作业
API-->>C: 202 已接受 (作业 ID)
Note over Q,W: 异步处理
Q->>W: 出队作业
W->>W: 处理作业
W->>N: 发送通知
N-->>C: 作业完成通知
实体关系图
基本 ERD
erDiagram
USER ||--o{ ORDER : 下单
USER {
uuid id PK
string email UK
string name
timestamp created_at
}
ORDER ||--|{ ORDER_ITEM : 包含
ORDER {
uuid id PK
uuid user_id FK
decimal total
string status
timestamp created_at
}
ORDER_ITEM }|--|| PRODUCT : 引用
ORDER_ITEM {
uuid id PK
uuid order_id FK
uuid product_id FK
int quantity
decimal price
}
PRODUCT ||--o{ PRODUCT_CATEGORY : 属于
PRODUCT {
uuid id PK
string name
text description
decimal price
int stock
}
CATEGORY ||--o{ PRODUCT_CATEGORY : 包含
CATEGORY {
uuid id PK
string name
uuid parent_id FK
}
PRODUCT_CATEGORY {
uuid product_id PK,FK
uuid category_id PK,FK
}
带关系说明的 ERD
erDiagram
CUSTOMER ||--o{ ORDER : "下单 (1:N)"
ORDER ||--|{ LINE_ITEM : "包含 (1:N, 必需)"
PRODUCT ||--o{ LINE_ITEM : "出现在 (1:N)"
CUSTOMER }|--|| ADDRESS : "拥有账单地址 (N:1, 必需)"
CUSTOMER }o--o{ ADDRESS : "拥有收货地址 (N:N)"
关系符号说明：
||恰好一个o|零或一个}|一个或多个}o零或多个
流程图
决策逻辑
flowchart TD
A[开始：用户登录] --> B{凭证有效？}
B -->|是| C{启用 2FA？}
B -->|否| D[显示错误消息]
D --> A
C -->|是| E[发送 2FA 验证码]
E --> F{验证码正确？}
F -->|是| G[创建会话]
F -->|否| H{尝试次数 < 3？}
H -->|是| E
H -->|否| I[锁定账户]
C -->|否| G
G --> J[重定向到仪表盘]
J --> K[结束]
I --> K
流程
flowchart LR
subgraph "CI 流水线"
A[推送代码] --> B[运行测试]
B --> C{测试通过？}
C -->|是| D[构建镜像]
C -->|否| E[通知开发者]
D --> F[推送到仓库]
end
subgraph "CD 流水线"
F --> G[部署到预发布环境]
G --> H[运行端到端测试]
H --> I{测试通过？}
I -->|是| J[部署到生产环境]
I -->|否| K[回滚]
end
状态图
订单状态机
stateDiagram-v2
[*] --> Draft: 创建订单
Draft --> Pending: 提交
Draft --> Cancelled: 取消
Pending --> Confirmed: 收到付款
Pending --> Cancelled: 付款失败
Pending --> Cancelled: 超时 (24h)
Confirmed --> Processing: 开始履约
Confirmed --> Cancelled: 客户取消
Processing --> Shipped: 发货
Processing --> Cancelled: 缺货
Shipped --> Delivered: 确认送达
Shipped --> Returned: 发起退货
Delivered --> Returned: 请求退货
Delivered --> [*]: 完成
Returned --> Refunded: 处理退款
Refunded --> [*]: 完成
Cancelled --> [*]: 完成
连接状态机
stateDiagram-v2
[*] --> Disconnected
Disconnected --> Connecting: connect()
Connecting --> Connected: 成功
Connecting --> Disconnected: 失败
Connected --> Disconnected: disconnect()
Connected --> Reconnecting: 连接丢失
Reconnecting --> Connected: 成功
Reconnecting --> Disconnected: 超过最大重试次数
note right of Reconnecting
指数退避
最多重试 5 次
end note
类图
classDiagram
class Repository~T~ {
<<interface>>
+findById(id: string) T
+findAll() List~T~
+save(entity: T) T
+delete(id: string) void
}
class UserRepository {
-db: Database
+findById(id: string) User
+findAll() List~User~
+save(entity: User) User
+delete(id: string) void
+findByEmail(email: string) User
}
class User {
+id: string
+email: string
+name: string
+createdAt: Date
+validate() boolean
}
Repository~T~ <|.. UserRepository
UserRepository --> User