技术图表制作Skill diagramming

---

名称: 图表绘制 描述: 使用Mermaid语法创建技术图表，用于架构图、序列图、ERD、流程图和状态机图。用于可视化系统设计、数据流和过程。触发词: diagram, diagrams, mermaid, plantuml, draw.io, excalidraw, flowchart, sequence diagram, class diagram, architecture diagram, ERD, entity relationship, entity-relationship, C4, C4 model, system context, container diagram, component diagram, state diagram, state machine, visualize, draw, chart, flow, data flow, API flow, system design, architecture visualization, UML.

图表绘制

概述

使用Mermaid语法创建清晰、可维护的技术图表。此技能涵盖用于记录软件系统的架构图、序列图、实体关系图、流程图和状态图。

指令

1. 选择正确的图表类型

图表类型	使用场景
架构图/C4	显示系统结构和组件
序列图	显示随时间变化的交互
ERD	显示数据模型和关系
流程图	显示决策逻辑和过程
状态图	显示状态转换

2. Mermaid语法模式

方向控制:

• flowchart TB - 从上到下
• flowchart LR - 从左到右
• sequenceDiagram - 自动从上到下布局

节点形状:

• [矩形] - 过程
• (圆角矩形) - 开始/结束
• {菱形} - 决策
• [(数据库)] - 存储
• ((圆形)) - 连接点

箭头类型:

• --> 实线 (流程)
• -.-> 虚线 (可选)
• ->> 粗线 (消息)
• -->> 虚线消息
• ==> 特粗线 (强调)

子图用于分组:

flowchart TB
    subgraph "子系统名称"
        A --> B
    end

3. 一般原则

• 保持图表聚焦于一个概念
• 使用一致的命名约定
• 为关系添加描述性标签
• 限制复杂性 (拆分大型图表)
• 使用注释进行文档记录

最佳实践

• 简洁性: 一个图表，一个概念
• 一致性: 相关图表使用相同命名
• 可读性: 从左到右或从上到下的流程
• 标签: 始终标记关系和转换
• 上下文: 包括标题和简要描述

示例

架构图 (C4模型)

C4模型提供分层系统可视化:

• 层级1 (上下文): 系统在其环境中的位置，外部依赖
• 层级2 (容器): 高级技术构建块 (应用、数据库、服务)
• 层级3 (组件): 容器的内部结构 (类、模块)

使用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

序列图

用于API流、请求/响应循环、分布式系统交互和多服务通信。

关键模式:

• participant - 提前定义参与者
• autonumber - 添加步骤编号
• alt/else/end - 条件流
• loop/end - 重复操作
• par/end - 并行操作
• Note over A,B - 添加解释性注释

基本请求流

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 用户
        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: 任务完成通知

API认证流

sequenceDiagram
    participant C as 客户端
    participant API as API网关
    participant Auth as 认证服务
    participant Cache as Redis缓存
    participant DB as 用户数据库

    C->>API: POST /login (凭证)
    API->>Auth: 验证凭证
    Auth->>DB: 查询用户
    DB-->>Auth: 用户记录

    alt 有效凭证
        Auth->>Auth: 生成JWT
        Auth->>Cache: 存储会话
        Cache-->>Auth: OK
        Auth-->>API: 令牌 + 刷新令牌
        API-->>C: 200 OK (令牌)
    else 无效凭证
        Auth-->>API: 无效凭证
        API-->>C: 401 未授权
    end

微服务通信

sequenceDiagram
    participant U as 用户
    participant API as API网关
    participant O as 订单服务
    participant I as 库存服务
    participant P as 支付服务
    participant Q as 消息队列

    U->>API: POST /orders
    API->>O: 创建订单

    par 检查库存和处理支付
        O->>I: 检查库存
        I-->>O: 库存可用
    and
        O->>P: 授权支付
        P-->>O: 支付授权
    end

    O->>I: 预留物品
    O->>P: 捕获支付

    alt 成功
        P-->>O: 支付捕获
        O->>Q: 发布 OrderCreated 事件
        O-->>API: 订单创建
        API-->>U: 201 创建
    else 支付失败
        P-->>O: 支付失败
        O->>I: 释放预留
        O-->>API: 支付失败
        API-->>U: 402 需要支付
    end

实体关系图

用于数据库模式设计、数据模型文档记录和关系映射。

基础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
    [*] --> 草稿: 创建订单

    草稿 --> 待处理: 提交
    草稿 --> 已取消: 取消

    待处理 --> 已确认: 收到支付
    待处理 --> 已取消: 支付失败
    待处理 --> 已取消: 超时 (24h)

    已确认 --> 处理中: 开始履行
    已确认 --> 已取消: 客户取消

    处理中 --> 已发货: 发货订单
    处理中 --> 已取消: 缺货

    已发货 --> 已交付: 交付确认
    已发货 --> 已退货: 退货发起

    已交付 --> 已退货: 退货请求
    已交付 --> [*]: 完成

    已退货 --> 已退款: 处理退款
    已退款 --> [*]: 完成

    已取消 --> [*]: 完成

连接状态机

stateDiagram-v2
    [*] --> 断开连接

    断开连接 --> 连接中: connect()
    连接中 --> 已连接: 成功
    连接中 --> 断开连接: 失败

    已连接 --> 断开连接: disconnect()
    已连接 --> 重新连接中: 连接丢失

    重新连接中 --> 已连接: 成功
    重新连接中 --> 断开连接: 最大重试

    note right of 重新连接中
        指数退避
        最多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