mermaid-diagram-specialist

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mermaid Diagram Specialist

Mermaid图表专家

Overview

概述

Purpose: Expert in creating comprehensive Mermaid diagrams for documentation, architecture visualization, and process mapping

Category: Tech Primary Users: tech-writer, architecture-validator, product-technical, tech-lead

用途：擅长创建用于文档编写、架构可视化和流程映射的全面Mermaid图表

类别：技术类 主要用户：技术文档工程师、架构验证人员、产品技术人员、技术负责人

When to Use This Skill

何时使用此技能

Creating architecture documentation
Visualizing workflows and processes
Documenting data models (ERDs)
Explaining sequence flows
Creating state machines
Documenting component relationships
Creating decision trees
Visualizing user journeys

创建架构文档
可视化工作流与流程
文档化数据模型（ERD）
解释序列流
创建状态机
文档化组件关系
创建决策树
可视化用户旅程

Prerequisites

前提条件

Required:

Understanding of the system/process to document
Access to technical specifications
Knowledge of diagram type needed

Optional:

Design system colors for consistency
Existing documentation to reference

必需条件：

理解需要文档化的系统/流程
可访问技术规范
了解所需的图表类型

可选条件：

用于保持一致性的设计系统配色
可参考的现有文档

Input

输入信息

What the skill needs:

Process/system description
Entities and relationships (for ERDs)
Component interactions (for sequence diagrams)
Architecture layers (for C4 diagrams)
States and transitions (for state diagrams)

此技能需要的内容：

流程/系统描述
实体与关系（用于ERD）
组件交互（用于时序图）
架构层级（用于C4图表）
状态与转换（用于状态图）

Workflow

工作流程

Step 1: Diagram Type Selection

步骤1：选择图表类型

Objective: Choose appropriate diagram type for requirements

Available Diagram Types:

Flowchart: Decision flows, algorithms, processes
Sequence Diagram: API interactions, message flows
ERD: Database schemas, entity relationships
Class Diagram: Object-oriented design
State Diagram: State machines, lifecycle
Gantt Chart: Project timelines, schedules
C4 Diagram: Architecture at different levels
Pie/Bar Charts: Data visualization
Git Graph: Version control flows
User Journey: User experience flows

Decision Matrix:

Process with decisions → Flowchart
API/system interactions → Sequence Diagram
Database structure → ERD
System architecture → C4 Diagram
Object relationships → Class Diagram
State transitions → State Diagram
Project timeline → Gantt Chart

Validation:

Diagram type matches content
Complexity appropriate
Audience considered
Purpose clear

Output: Selected diagram type

目标：根据需求选择合适的图表类型

可用图表类型：

流程图：决策流程、算法、过程
时序图：API交互、消息流
ERD：数据库模式、实体关系
类图：面向对象设计
状态图：状态机、生命周期
甘特图：项目时间线、进度计划
C4图表：不同层级的架构
饼图/柱状图：数据可视化
Git图：版本控制流程
用户旅程图：用户体验流程

决策矩阵：

带决策的流程 → 流程图
API/系统交互 → 时序图
数据库结构 → ERD
系统架构 → C4图表
对象关系 → 类图
状态转换 → 状态图
项目时间线 → 甘特图

验证项：

图表类型与内容匹配
复杂度合适
考虑了受众
用途明确

输出：选定的图表类型

Step 2: Flowchart Creation

步骤2：创建流程图

Objective: Create process and decision flow diagrams

Syntax:

mermaid

flowchart TD
    Start([Start]) --> Input[/User Input/]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Error --> Input
    Process --> Save[(Save to DB)]
    Save --> Success[/Success Response/]
    Success --> End([End])

Node Shapes:

```
[Rectangle]
```
- Process step
```
([Rounded])
```
- Start/End
```
{Diamond}
```
- Decision
```
[/Parallelogram/]
```
- Input/Output
```
[(Database)]
```
- Data storage
```
((Circle))
```
- Connector

Direction Options:

```
TD
```
- Top to Down
```
LR
```
- Left to Right
```
BT
```
- Bottom to Top
```
RL
```
- Right to Left

Example - Booking Flow:

mermaid

flowchart TD
    Start([User Initiates Booking]) --> CheckDates[Check Date Availability]
    CheckDates --> Available{Dates Available?}
    Available -->|No| ShowError[/Show Unavailable Message/]
    ShowError --> End([End])
    Available -->|Yes| CreateBooking[Create Pending Booking]
    CreateBooking --> Payment[Process Payment]
    Payment --> PaymentSuccess{Payment Success?}
    PaymentSuccess -->|No| CancelBooking[Cancel Booking]
    CancelBooking --> ShowError
    PaymentSuccess -->|Yes| ConfirmBooking[Confirm Booking]
    ConfirmBooking --> SendEmail[/Send Confirmation Email/]
    SendEmail --> SaveDB[(Save to Database)]
    SaveDB --> Success[/Show Success/]
    Success --> End

Validation:

All paths covered
Decision points clear
Start and end defined
Flow direction logical

Output: Process flowchart

目标：创建流程与决策流程图

语法：

mermaid

flowchart TD
    Start([Start]) --> Input[/User Input/]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Error --> Input
    Process --> Save[(Save to DB)]
    Save --> Success[/Success Response/]
    Success --> End([End])

节点形状：

```
[Rectangle]
```
- 流程步骤
```
([Rounded])
```
- 开始/结束
```
{Diamond}
```
- 决策点
```
[/Parallelogram/]
```
- 输入/输出
```
[(Database)]
```
- 数据存储
```
((Circle))
```
- 连接器

方向选项：

```
TD
```
- 从上到下
```
LR
```
- 从左到右
```
BT
```
- 从下到上
```
RL
```
- 从右到左

示例 - 预订流程：

mermaid

flowchart TD
    Start([User Initiates Booking]) --> CheckDates[Check Date Availability]
    CheckDates --> Available{Dates Available?}
    Available -->|No| ShowError[/Show Unavailable Message/]
    ShowError --> End([End])
    Available -->|Yes| CreateBooking[Create Pending Booking]
    CreateBooking --> Payment[Process Payment]
    Payment --> PaymentSuccess{Payment Success?}
    PaymentSuccess -->|No| CancelBooking[Cancel Booking]
    CancelBooking --> ShowError
    PaymentSuccess -->|Yes| ConfirmBooking[Confirm Booking]
    ConfirmBooking --> SendEmail[/Send Confirmation Email/]
    SendEmail --> SaveDB[(Save to Database)]
    SaveDB --> Success[/Show Success/]
    Success --> End

验证项：

覆盖所有路径
决策点清晰
定义了开始与结束
流向逻辑合理

输出：流程流程图

Step 3: Sequence Diagram Creation

步骤3：创建时序图

Objective: Document API interactions and message flows

Syntax:

mermaid

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant DB
    participant Payment

    User->>Frontend: Click "Book"
    Frontend->>API: POST /api/bookings
    API->>DB: Check availability
    DB-->>API: Available
    API->>Payment: Process payment
    Payment-->>API: Payment successful
    API->>DB: Create booking
    DB-->>API: Booking created
    API-->>Frontend: 201 Created
    Frontend-->>User: Show confirmation

Participant Types:

```
actor
```
- Human user
```
participant
```
- System/Service
```
database
```
- Database

Arrow Types:

```
->
```
- Solid line (synchronous)
```
-->
```
- Dotted line (response)
```
->>
```
- Solid arrow (async message)
```
-->>
```
- Dotted arrow (async response)

Example - Authentication Flow:

mermaid

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant Clerk
    participant DB

    User->>Frontend: Enter credentials
    Frontend->>Clerk: Login request
    Clerk->>Clerk: Validate credentials
    alt Credentials valid
        Clerk-->>Frontend: JWT token
        Frontend->>API: Request with token
        API->>Clerk: Verify token
        Clerk-->>API: Token valid
        API->>DB: Fetch user data
        DB-->>API: User data
        API-->>Frontend: User session
        Frontend-->>User: Logged in
    else Credentials invalid
        Clerk-->>Frontend: Auth error
        Frontend-->>User: Show error
    end

Validation:

All participants identified
Message flow logical
Return messages shown
Alt/loop blocks used correctly

Output: Sequence diagram

目标：文档化API交互与消息流

语法：

mermaid

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant DB
    participant Payment

    User->>Frontend: Click "Book"
    Frontend->>API: POST /api/bookings
    API->>DB: Check availability
    DB-->>API: Available
    API->>Payment: Process payment
    Payment-->>API: Payment successful
    API->>DB: Create booking
    DB-->>API: Booking created
    API-->>Frontend: 201 Created
    Frontend-->>User: Show confirmation

参与者类型：

```
actor
```
- 人类用户
```
participant
```
- 系统/服务
```
database
```
- 数据库

箭头类型：

```
->
```
- 实线（同步）
```
-->
```
- 虚线（响应）
```
->>
```
- 实箭头（异步消息）
```
-->>
```
- 虚箭头（异步响应）

示例 - 认证流程：

mermaid

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant Clerk
    participant DB

    User->>Frontend: Enter credentials
    Frontend->>Clerk: Login request
    Clerk->>Clerk: Validate credentials
    alt Credentials valid
        Clerk-->>Frontend: JWT token
        Frontend->>API: Request with token
        API->>Clerk: Verify token
        Clerk-->>API: Token valid
        API->>DB: Fetch user data
        DB-->>API: User data
        API-->>Frontend: User session
        Frontend-->>User: Logged in
    else Credentials invalid
        Clerk-->>Frontend: Auth error
        Frontend-->>User: Show error
    end

验证项：

识别所有参与者
消息流向逻辑合理
显示返回消息
正确使用Alt/循环块

输出：时序图

Step 4: ERD Creation

步骤4：创建ERD

Objective: Document database schema and relationships

Syntax:

mermaid

erDiagram
    USER ||--o{ BOOKING : creates
    ACCOMMODATION ||--o{ BOOKING : "booked for"
    USER {
        uuid id PK
        string email UK
        string name
        timestamp created_at
    }
    BOOKING {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        date check_in
        date check_out
        enum status
    }
    ACCOMMODATION {
        uuid id PK
        string name
        text description
        decimal price_per_night
    }

Relationship Types:

```
||--||
```
- One to one
```
||--o{
```
- One to many
```
}o--o{
```
- Many to many
```
||--o|
```
- One to zero or one

Cardinality Symbols:

```
||
```
- Exactly one
```
o|
```
- Zero or one
```
}o
```
- Zero or more
```
}|
```
- One or more

Example - Full Hospeda ERD:

mermaid

erDiagram
    USER ||--o{ BOOKING : creates
    USER ||--o{ REVIEW : writes
    USER ||--o{ ACCOMMODATION : owns
    ACCOMMODATION ||--o{ BOOKING : "has bookings"
    ACCOMMODATION ||--o{ REVIEW : "has reviews"
    ACCOMMODATION }o--o{ AMENITY : includes
    BOOKING ||--|| PAYMENT : "has payment"

    USER {
        uuid id PK
        string clerk_id UK
        string email UK
        string name
        enum role
        timestamp created_at
    }

    ACCOMMODATION {
        uuid id PK
        uuid owner_id FK
        string name
        text description
        decimal price_per_night
        int max_guests
        enum status
    }

    BOOKING {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        date check_in
        date check_out
        int guests
        enum status
        decimal total_price
    }

    REVIEW {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        int rating
        text comment
        timestamp created_at
    }

    PAYMENT {
        uuid id PK
        uuid booking_id FK
        string mercadopago_id UK
        decimal amount
        enum status
        timestamp processed_at
    }

    AMENITY {
        uuid id PK
        string name
        string icon
    }

Validation:

All entities defined
Relationships accurate
Cardinality correct
Primary/Foreign keys marked

Output: ERD diagram

目标：文档化数据库模式与关系

语法：

mermaid

erDiagram
    USER ||--o{ BOOKING : creates
    ACCOMMODATION ||--o{ BOOKING : "booked for"
    USER {
        uuid id PK
        string email UK
        string name
        timestamp created_at
    }
    BOOKING {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        date check_in
        date check_out
        enum status
    }
    ACCOMMODATION {
        uuid id PK
        string name
        text description
        decimal price_per_night
    }

关系类型：

```
||--||
```
- 一对一
```
||--o{
```
- 一对多
```
}o--o{
```
- 多对多
```
||--o|
```
- 一对零或一

基数符号：

```
||
```
- 恰好一个
```
o|
```
- 零或一个
```
}o
```
- 零或多个
```
}|
```
- 一个或多个

示例 - 完整Hospeda ERD：

mermaid

erDiagram
    USER ||--o{ BOOKING : creates
    USER ||--o{ REVIEW : writes
    USER ||--o{ ACCOMMODATION : owns
    ACCOMMODATION ||--o{ BOOKING : "has bookings"
    ACCOMMODATION ||--o{ REVIEW : "has reviews"
    ACCOMMODATION }o--o{ AMENITY : includes
    BOOKING ||--|| PAYMENT : "has payment"

    USER {
        uuid id PK
        string clerk_id UK
        string email UK
        string name
        enum role
        timestamp created_at
    }

    ACCOMMODATION {
        uuid id PK
        uuid owner_id FK
        string name
        text description
        decimal price_per_night
        int max_guests
        enum status
    }

    BOOKING {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        date check_in
        date check_out
        int guests
        enum status
        decimal total_price
    }

    REVIEW {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        int rating
        text comment
        timestamp created_at
    }

    PAYMENT {
        uuid id PK
        uuid booking_id FK
        string mercadopago_id UK
        decimal amount
        enum status
        timestamp processed_at
    }

    AMENITY {
        uuid id PK
        string name
        string icon
    }

验证项：

定义所有实体
关系准确
基数正确
标记主键/外键

输出：ERD图表

Step 5: C4 Architecture Diagrams

步骤5：创建C4架构图表

Objective: Document system architecture at different levels

Context Level (System in environment):

mermaid

C4Context
    title System Context - Hospeda Platform

    Person(guest, "Guest", "Tourist looking for accommodation")
    Person(owner, "Owner", "Accommodation owner")
    System(hospeda, "Hospeda Platform", "Tourism booking platform")

    System_Ext(clerk, "Clerk", "Authentication provider")
    System_Ext(mercadopago, "Mercado Pago", "Payment processor")
    System_Ext(email, "Email Service", "Transactional emails")

    Rel(guest, hospeda, "Searches and books", "HTTPS")
    Rel(owner, hospeda, "Manages listings", "HTTPS")
    Rel(hospeda, clerk, "Authenticates users", "API")
    Rel(hospeda, mercadopago, "Processes payments", "API")
    Rel(hospeda, email, "Sends notifications", "SMTP")

Container Level (Applications and data stores):

mermaid

C4Container
    title Container - Hospeda Platform

    Person(user, "User")

    Container(web, "Web App", "Astro + React", "Public-facing website")
    Container(admin, "Admin Panel", "TanStack Start", "Management interface")
    Container(api, "API", "Hono", "Backend services")
    ContainerDb(db, "Database", "PostgreSQL", "Stores all data")

    Rel(user, web, "Uses", "HTTPS")
    Rel(user, admin, "Manages", "HTTPS")
    Rel(web, api, "Calls", "JSON/HTTPS")
    Rel(admin, api, "Calls", "JSON/HTTPS")
    Rel(api, db, "Reads/Writes", "SQL")

Component Level (Internal structure):

mermaid

C4Component
    title Components - API Application

    Container(api, "API", "Hono")

    Component(routes, "Routes", "Hono Router", "HTTP endpoints")
    Component(services, "Services", "Business Logic", "Domain operations")
    Component(models, "Models", "Data Access", "DB operations")
    Component(middleware, "Middleware", "Cross-cutting", "Auth, logging, errors")

    Rel(routes, middleware, "Uses")
    Rel(routes, services, "Calls")
    Rel(services, models, "Uses")
    Rel(models, db, "Queries")

Validation:

Appropriate level selected
All systems/containers shown
Relationships clear
External systems identified

Output: C4 architecture diagrams

目标：文档化不同层级的系统架构

上下文层级（环境中的系统）：

mermaid

C4Context
    title System Context - Hospeda Platform

    Person(guest, "Guest", "Tourist looking for accommodation")
    Person(owner, "Owner", "Accommodation owner")
    System(hospeda, "Hospeda Platform", "Tourism booking platform")

    System_Ext(clerk, "Clerk", "Authentication provider")
    System_Ext(mercadopago, "Mercado Pago", "Payment processor")
    System_Ext(email, "Email Service", "Transactional emails")

    Rel(guest, hospeda, "Searches and books", "HTTPS")
    Rel(owner, hospeda, "Manages listings", "HTTPS")
    Rel(hospeda, clerk, "Authenticates users", "API")
    Rel(hospeda, mercadopago, "Processes payments", "API")
    Rel(hospeda, email, "Sends notifications", "SMTP")

容器层级（应用与数据存储）：

mermaid

C4Container
    title Container - Hospeda Platform

    Person(user, "User")

    Container(web, "Web App", "Astro + React", "Public-facing website")
    Container(admin, "Admin Panel", "TanStack Start", "Management interface")
    Container(api, "API", "Hono", "Backend services")
    ContainerDb(db, "Database", "PostgreSQL", "Stores all data")

    Rel(user, web, "Uses", "HTTPS")
    Rel(user, admin, "Manages", "HTTPS")
    Rel(web, api, "Calls", "JSON/HTTPS")
    Rel(admin, api, "Calls", "JSON/HTTPS")
    Rel(api, db, "Reads/Writes", "SQL")

组件层级（内部结构）：

mermaid

C4Component
    title Components - API Application

    Container(api, "API", "Hono")

    Component(routes, "Routes", "Hono Router", "HTTP endpoints")
    Component(services, "Services", "Business Logic", "Domain operations")
    Component(models, "Models", "Data Access", "DB operations")
    Component(middleware, "Middleware", "Cross-cutting", "Auth, logging, errors")

    Rel(routes, middleware, "Uses")
    Rel(routes, services, "Calls")
    Rel(services, models, "Uses")
    Rel(models, db, "Queries")

验证项：

选择了合适的层级
显示所有系统/容器
关系清晰
识别外部系统

输出：C4架构图表

Step 6: State Diagram Creation

步骤6：创建状态图

Objective: Document state machines and lifecycles

Syntax:

mermaid

stateDiagram-v2
    [*] --> Pending
    Pending --> Confirmed : Payment Success
    Pending --> Cancelled : Payment Failed
    Pending --> Cancelled : User Cancels
    Confirmed --> CheckedIn : Check-in Date
    Confirmed --> Cancelled : Cancellation Request
    CheckedIn --> CheckedOut : Check-out Date
    CheckedOut --> Reviewed : User Submits Review
    CheckedOut --> [*] : 30 Days Elapsed
    Reviewed --> [*]
    Cancelled --> [*]

Example - Booking Lifecycle:

mermaid

stateDiagram-v2
    [*] --> Draft : Create Booking

    state "Pending Payment" as Pending
    state "Payment Processing" as Processing

    Draft --> Pending : Submit Booking
    Pending --> Processing : Initiate Payment

    Processing --> Confirmed : Payment Approved
    Processing --> PaymentFailed : Payment Declined

    PaymentFailed --> Pending : Retry Payment
    PaymentFailed --> Cancelled : Max Retries

    Confirmed --> Active : Check-in Date Reached
    Active --> Completed : Check-out Date Reached

    Confirmed --> CancelRequested : Cancellation Request
    CancelRequested --> RefundProcessing : Approve Cancellation
    RefundProcessing --> Cancelled : Refund Complete

    Completed --> [*]
    Cancelled --> [*]

    note right of Confirmed
        Owner notified
        Calendar blocked
    end note

    note right of Completed
        Review requested
        Payment released
    end note

Validation:

All states defined
Transitions logical
Start/end states marked
Notes explain key states

Output: State diagram

目标：文档化状态机与生命周期

语法：

mermaid

stateDiagram-v2
    [*] --> Pending
    Pending --> Confirmed : Payment Success
    Pending --> Cancelled : Payment Failed
    Pending --> Cancelled : User Cancels
    Confirmed --> CheckedIn : Check-in Date
    Confirmed --> Cancelled : Cancellation Request
    CheckedIn --> CheckedOut : Check-out Date
    CheckedOut --> Reviewed : User Submits Review
    CheckedOut --> [*] : 30 Days Elapsed
    Reviewed --> [*]
    Cancelled --> [*]

示例 - 预订生命周期：

mermaid

stateDiagram-v2
    [*] --> Draft : Create Booking

    state "Pending Payment" as Pending
    state "Payment Processing" as Processing

    Draft --> Pending : Submit Booking
    Pending --> Processing : Initiate Payment

    Processing --> Confirmed : Payment Approved
    Processing --> PaymentFailed : Payment Declined

    PaymentFailed --> Pending : Retry Payment
    PaymentFailed --> Cancelled : Max Retries

    Confirmed --> Active : Check-in Date Reached
    Active --> Completed : Check-out Date Reached

    Confirmed --> CancelRequested : Cancellation Request
    CancelRequested --> RefundProcessing : Approve Cancellation
    RefundProcessing --> Cancelled : Refund Complete

    Completed --> [*]
    Cancelled --> [*]

    note right of Confirmed
        Owner notified
        Calendar blocked
    end note

    note right of Completed
        Review requested
        Payment released
    end note

验证项：

定义所有状态
转换逻辑合理
标记开始/结束状态
备注说明关键状态

输出：状态图

Step 7: Styling and Customization

步骤7：样式与自定义

Objective: Apply consistent styling to diagrams

Theme Application:

mermaid

%%{init: {'theme':'base', 'themeVariables': {
  'primaryColor':'#3B82F6',
  'primaryTextColor':'#fff',
  'primaryBorderColor':'#2563EB',
  'lineColor':'#6B7280',
  'secondaryColor':'#10B981',
  'tertiaryColor':'#F59E0B'
}}}%%
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]

Class Styling:

mermaid

flowchart TD
    A[Normal] --> B[Success]
    B --> C[Error]

    classDef successClass fill:#10B981,stroke:#059669,color:#fff
    classDef errorClass fill:#EF4444,stroke:#DC2626,color:#fff

    class B successClass
    class C errorClass

Validation:

Colors match brand
Contrast sufficient
Styling consistent
Readable in both themes

Output: Styled diagrams

目标：为图表应用一致的样式

主题应用：

mermaid

%%{init: {'theme':'base', 'themeVariables': {
  'primaryColor':'#3B82F6',
  'primaryTextColor':'#fff',
  'primaryBorderColor':'#2563EB',
  'lineColor':'#6B7280',
  'secondaryColor':'#10B981',
  'tertiaryColor':'#F59E0B'
}}}%%
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]

类样式：

mermaid

flowchart TD
    A[Normal] --> B[Success]
    B --> C[Error]

    classDef successClass fill:#10B981,stroke:#059669,color:#fff
    classDef errorClass fill:#EF4444,stroke:#DC2626,color:#fff

    class B successClass
    class C errorClass

验证项：

配色符合品牌规范
对比度足够
样式一致
在两种主题下都可读

输出：带样式的图表

Output

输出

Produces:

Mermaid diagram code in markdown
Multiple diagram types as needed
Styled and themed diagrams
Documentation-ready visualizations

Success Criteria:

Diagram accurately represents system
All elements properly labeled
Relationships clear and correct
Styling consistent with brand
Renders correctly in markdown

生成内容：

Markdown格式的Mermaid图表代码
根据需要生成多种类型的图表
带样式与主题的图表
可直接用于文档的可视化内容

成功标准：

图表准确表示系统
所有元素都有合适的标签
关系清晰且正确
样式符合品牌规范
在Markdown中正确渲染

Best Practices

最佳实践

Simplicity: Keep diagrams focused and uncluttered
Labels: Clear, descriptive labels for all elements
Direction: Consistent flow direction (usually top-down or left-right)
Grouping: Use subgraphs to group related elements
Colors: Use color to highlight important elements
Notes: Add notes to explain complex logic
Levels: Use appropriate abstraction level for audience
Updates: Keep diagrams in sync with code
Comments: Add comments in mermaid code for maintainability
Testing: Verify diagrams render in target platform

简洁性：保持图表聚焦且整洁
标签：为所有元素使用清晰、描述性的标签
方向：保持一致的流向（通常为从上到下或从左到右）
分组：使用子图对相关元素进行分组
颜色：使用颜色突出重要元素
备注：添加备注解释复杂逻辑
层级：为受众选择合适的抽象层级
更新：保持图表与代码同步
注释：在Mermaid代码中添加注释以提高可维护性
测试：在目标平台中验证图表渲染效果

Common Patterns

常见模式

API Request Flow

API请求流程

mermaid

sequenceDiagram
    Client->>+API: GET /resource
    API->>+Service: fetchResource()
    Service->>+Model: findById()
    Model->>+DB: SELECT query
    DB-->>-Model: Row data
    Model-->>-Service: Entity
    Service-->>-API: DTO
    API-->>-Client: JSON response

mermaid

sequenceDiagram
    Client->>+API: GET /resource
    API->>+Service: fetchResource()
    Service->>+Model: findById()
    Model->>+DB: SELECT query
    DB-->>-Model: Row data
    Model-->>-Service: Entity
    Service-->>-API: DTO
    API-->>-Client: JSON response

Error Handling Flow

错误处理流程

mermaid

flowchart TD
    Request[Incoming Request] --> Validate{Valid?}
    Validate -->|No| ValidationError[Validation Error]
    ValidationError --> ErrorHandler[Error Handler]
    Validate -->|Yes| Process[Process Request]
    Process --> DB{DB Success?}
    DB -->|No| DBError[Database Error]
    DBError --> ErrorHandler
    DB -->|Yes| Success[Success Response]
    ErrorHandler --> LogError[Log Error]
    LogError --> ErrorResponse[Error Response]

mermaid

flowchart TD
    Request[Incoming Request] --> Validate{Valid?}
    Validate -->|No| ValidationError[Validation Error]
    ValidationError --> ErrorHandler[Error Handler]
    Validate -->|Yes| Process[Process Request]
    Process --> DB{DB Success?}
    DB -->|No| DBError[Database Error]
    DBError --> ErrorHandler
    DB -->|Yes| Success[Success Response]
    ErrorHandler --> LogError[Log Error]
    LogError --> ErrorResponse[Error Response]

Notes

注意事项

Mermaid renders in GitHub, GitLab, Notion, and most markdown viewers
Live editor available at mermaid.live
Maximum complexity: Keep under 20 nodes for readability
Use subgraphs for grouping related nodes
Test rendering in target platform before committing
Keep diagram source in markdown files, not images
Version control diagrams with code
Update diagrams during code review

Mermaid可在GitHub、GitLab、Notion及大多数Markdown查看器中渲染
在线编辑器可访问mermaid.live
最大复杂度：保持节点数量在20个以内以保证可读性
使用子图对相关节点进行分组
在提交前在目标平台测试渲染效果
将图表源代码保存在Markdown文件中，而非图片
与代码一起对图表进行版本控制
在代码评审期间更新图表