dotnet-mermaid-diagrams

dotnet-mermaid-diagrams

面向 .NET 项目的 Mermaid 图表参考：架构图（C4 风格的上下文图、容器图、组件视图、分层架构、微服务拓扑）、时序图（API 请求流、async/await 模式、中间件管道、身份验证流程）、类图（领域模型、DI 注册图、继承层次结构、接口实现）、部署图（容器部署、Kubernetes Pod 布局、CI/CD 管道流程）、ER 图（EF Core 模型关系、数据库架构可视化）、状态图（工作流状态、订单处理、Saga 模式、状态机模式）和流程图（决策树、框架选择、架构选择）。其中包含有关命名、分组、GitHub 渲染和深色模式注意事项的图表即代码约定。

版本假设： Mermaid v10+（GitHub、Starlight、Docusaurus 原生支持）。GitHub 会在 Markdown 文件、议题、PR 和讨论中渲染 Mermaid。.NET 代码示例以 .NET 8.0+ 为基准。

范围边界： 此技能负责 Mermaid 图表语法和 .NET 专用图表模式——包括实际图表内容、约定和渲染提示。Mermaid 渲染的文档平台配置（Starlight 插件、Docusaurus 主题、DocFX 模板）由 [skill:dotnet-documentation-strategy] 负责。GitHub 原生文档结构（README、CONTRIBUTING、模板）由 [skill:dotnet-github-docs] 负责。

不在范围内： Mermaid 渲染的文档平台配置——请参阅 [skill:dotnet-documentation-strategy]。GitHub 原生文档结构和嵌入图表的 README 模式——请参阅 [skill:dotnet-github-docs]。包含图表的文档站点的 CI/CD 管道部署——请参阅 [skill:dotnet-gha-deploy]。

交叉引用：[skill:dotnet-documentation-strategy]，了解跨文档平台的 Mermaid 渲染设置；[skill:dotnet-github-docs]，了解如何在 GitHub 原生文档中嵌入图表；[skill:dotnet-gha-deploy]，了解文档站点部署。

---

架构图

C4 风格上下文图

展示系统所处的环境以及外部参与者和系统。

graph TB
    User["End User<br/>(Browser/Mobile)"]
    Admin["Admin<br/>(Internal)"]

    subgraph System["My .NET Application"]
        API["ASP.NET Core API<br/>(.NET 8)"]
    end

    ExtAuth["Identity Provider<br/>(Azure AD / Auth0)"]
    ExtEmail["Email Service<br/>(SendGrid)"]
    ExtPay["Payment Gateway<br/>(Stripe)"]

    User -->|"HTTPS"| API
    Admin -->|"HTTPS"| API
    API -->|"OAuth 2.0"| ExtAuth
    API -->|"SMTP/API"| ExtEmail
    API -->|"REST API"| ExtPay

C4 风格容器图

展示高层技术选型及其交互方式。

graph TB
    subgraph Client["Client Tier"]
        SPA["Blazor WASM<br/>(WebAssembly)"]
        Mobile["MAUI App<br/>(.NET 8)"]
    end

    subgraph API_Tier["API Tier"]
        Gateway["API Gateway<br/>(YARP)"]
        OrderAPI["Order Service<br/>(ASP.NET Core)"]
        CatalogAPI["Catalog Service<br/>(ASP.NET Core)"]
        IdentityAPI["Identity Service<br/>(Duende IdentityServer)"]
    end

    subgraph Data_Tier["Data Tier"]
        OrderDB[("Order DB<br/>(SQL Server)")]
        CatalogDB[("Catalog DB<br/>(PostgreSQL)")]
        Cache[("Redis Cache")]
        Bus["Message Bus<br/>(RabbitMQ)"]
    end

    SPA -->|"HTTPS"| Gateway
    Mobile -->|"HTTPS"| Gateway
    Gateway --> OrderAPI
    Gateway --> CatalogAPI
    Gateway --> IdentityAPI
    OrderAPI --> OrderDB
    OrderAPI --> Cache
    OrderAPI --> Bus
    CatalogAPI --> CatalogDB
    CatalogAPI --> Cache
    Bus --> CatalogAPI

C4 风格组件图

展示单个服务的内部结构。

graph TB
    subgraph OrderService["Order Service"]
        Controllers["Controllers<br/>(API Endpoints)"]
        Validators["FluentValidation<br/>(Request Validators)"]
        Handlers["MediatR Handlers<br/>(Business Logic)"]
        DomainModels["Domain Models<br/>(Entities, Value Objects)"]
        Repos["Repositories<br/>(EF Core)"]
        Events["Domain Events<br/>(MediatR Notifications)"]
        IntEvents["Integration Events<br/>(MassTransit)"]
    end

    Controllers --> Validators
    Controllers --> Handlers
    Handlers --> DomainModels
    Handlers --> Repos
    Handlers --> Events
    Events --> IntEvents

分层架构

graph TB
    subgraph Presentation["Presentation Layer"]
        API["ASP.NET Core Controllers / Minimal APIs"]
        Blazor["Blazor Components"]
    end

    subgraph Application["Application Layer"]
        Services["Application Services"]
        DTOs["DTOs / View Models"]
        Mappings["AutoMapper Profiles"]
        CQRS["MediatR Handlers"]
    end

    subgraph Domain["Domain Layer"]
        Entities["Entities"]
        ValueObjects["Value Objects"]
        DomainEvents["Domain Events"]
        Interfaces["Repository Interfaces"]
    end

    subgraph Infrastructure["Infrastructure Layer"]
        EFCore["EF Core DbContext"]
        Repositories["Repository Implementations"]
        ExternalServices["External Service Clients"]
        Messaging["MassTransit / RabbitMQ"]
    end

    Presentation --> Application
    Application --> Domain
    Infrastructure --> Domain
    Infrastructure -.->|"implements"| Interfaces

微服务拓扑

graph LR
    subgraph Ingress
        LB["Load Balancer"]
        GW["API Gateway<br/>(YARP)"]
    end

    subgraph Services
        S1["Order Service"]
        S2["Catalog Service"]
        S3["Identity Service"]
        S4["Notification Service"]
    end

    subgraph Messaging
        MQ["RabbitMQ"]
    end

    subgraph Observability
        SEQ["Seq / ELK"]
        OTEL["OpenTelemetry Collector"]
    end

    LB --> GW
    GW --> S1
    GW --> S2
    GW --> S3
    S1 -->|"publish"| MQ
    MQ -->|"subscribe"| S2
    MQ -->|"subscribe"| S4
    S1 -.->|"traces"| OTEL
    S2 -.->|"traces"| OTEL
    S1 -.->|"logs"| SEQ
    S2 -.->|"logs"| SEQ

---

时序图

API 请求流

sequenceDiagram
    participant Client
    participant Middleware as ASP.NET Middleware
    participant Auth as Authentication
    participant Controller
    participant Service
    participant DB as Database

    Client->>Middleware: POST /api/orders
    Middleware->>Auth: Validate JWT
    Auth-->>Middleware: Claims Principal
    Middleware->>Controller: OrdersController.Create()
    Controller->>Service: CreateOrderAsync(dto)
    Service->>DB: INSERT INTO Orders
    DB-->>Service: Order entity
    Service-->>Controller: OrderResponse
    Controller-->>Client: 201 Created

Async/Await 模式

sequenceDiagram
    participant Caller
    participant Service as OrderService
    participant Repo as IOrderRepository
    participant DB as SQL Server
    participant Cache as Redis

    Caller->>+Service: GetOrderAsync(id)
    Service->>+Cache: GetAsync(key)
    Cache-->>-Service: null (cache miss)
    Service->>+Repo: FindByIdAsync(id)
    Repo->>+DB: SELECT ... WHERE Id = @id
    Note over Repo,DB: await - thread returned to pool
    DB-->>-Repo: Row data
    Repo-->>-Service: Order entity
    Service->>+Cache: SetAsync(key, order, expiry)
    Note over Service,Cache: Fire-and-forget or await
    Cache-->>-Service: OK
    Service-->>-Caller: Order

中间件管道

sequenceDiagram
    participant Client
    participant ExHandler as ExceptionHandler
    participant HSTS as HSTS Middleware
    participant Auth as Authentication
    participant Authz as Authorization
    participant CORS as CORS Middleware
    participant Routing as Routing
    participant Endpoint

    Client->>ExHandler: HTTP Request
    ExHandler->>HSTS: next()
    HSTS->>Auth: next()
    Auth->>Authz: next()
    Authz->>CORS: next()
    CORS->>Routing: next()
    Routing->>Endpoint: Matched endpoint
    Endpoint-->>Routing: Response
    Routing-->>CORS: Response
    CORS-->>Authz: Response
    Authz-->>Auth: Response
    Auth-->>HSTS: Response
    HSTS-->>ExHandler: Response
    ExHandler-->>Client: HTTP Response

身份验证流程（OAuth 2.0 / OIDC）

sequenceDiagram
    participant User
    participant App as Blazor App
    participant BFF as BFF (ASP.NET Core)
    participant IDP as Identity Provider
    participant API as Protected API

    User->>App: Navigate to protected page
    App->>BFF: GET /api/user (no cookie)
    BFF-->>App: 401 Unauthorized
    App->>BFF: GET /login
    BFF->>IDP: Authorization Code + PKCE
    IDP->>User: Login page
    User->>IDP: Credentials
    IDP->>BFF: Authorization code
    BFF->>IDP: Exchange code for tokens
    IDP-->>BFF: Access + Refresh + ID tokens
    BFF-->>App: Set-Cookie (session)
    App->>BFF: GET /api/orders (with cookie)
    BFF->>API: GET /api/orders (Bearer token)
    API-->>BFF: Order data
    BFF-->>App: Order data

---

类图

领域模型

classDiagram
    class Order {
        +Guid Id
        +DateTime CreatedAt
        +OrderStatus Status
        +decimal TotalAmount
        +List~OrderLine~ Lines
        +AddLine(product, quantity)
        +Submit()
        +Cancel(reason)
    }

    class OrderLine {
        +Guid Id
        +Guid ProductId
        +string ProductName
        +int Quantity
        +decimal UnitPrice
        +decimal LineTotal
    }

    class OrderStatus {
        <<enumeration>>
        Draft
        Submitted
        Processing
        Shipped
        Delivered
        Cancelled
    }

    class Customer {
        +Guid Id
        +string Name
        +string Email
        +Address ShippingAddress
        +List~Order~ Orders
    }

    class Address {
        <<value object>>
        +string Street
        +string City
        +string State
        +string PostalCode
        +string Country
    }

    Order "1" --> "*" OrderLine : contains
    Order --> OrderStatus : has
    Customer "1" --> "*" Order : places
    Customer --> Address : has

DI 注册图

graph TB
    subgraph Singleton
        S1["IConfiguration"]
        S2["IMemoryCache"]
        S3["IHttpClientFactory"]
    end

    subgraph Scoped["Scoped (per-request)"]
        SC1["DbContext"]
        SC2["IOrderRepository"]
        SC3["ICurrentUser"]
    end

    subgraph Transient
        T1["IValidator~CreateOrderCommand~"]
        T2["INotificationSender"]
    end

    SC2 -->|"depends on"| SC1
    SC2 -->|"depends on"| S2
    T2 -->|"depends on"| S3
    SC3 -->|"depends on"| S1

    style Singleton fill:#e1f5fe
    style Scoped fill:#f3e5f5
    style Transient fill:#fff3e0

接口实现层次结构

classDiagram
    class IRepository~T~ {
        <<interface>>
        +GetByIdAsync(id) Task~T~
        +ListAsync() Task~List~T~~
        +AddAsync(entity) Task
        +UpdateAsync(entity) Task
        +DeleteAsync(id) Task
    }

    class IOrderRepository {
        <<interface>>
        +GetByCustomerAsync(customerId) Task~List~Order~~
        +GetPendingAsync() Task~List~Order~~
    }

    class RepositoryBase~T~ {
        <<abstract>>
        #DbContext _context
        +GetByIdAsync(id) Task~T~
        +ListAsync() Task~List~T~~
        +AddAsync(entity) Task
        +UpdateAsync(entity) Task
        +DeleteAsync(id) Task
    }

    class OrderRepository {
        +GetByCustomerAsync(customerId) Task~List~Order~~
        +GetPendingAsync() Task~List~Order~~
    }

    IRepository~T~ <|.. RepositoryBase~T~ : implements
    IOrderRepository <|.. OrderRepository : implements
    RepositoryBase~T~ <|-- OrderRepository : extends
    IRepository~T~ <|-- IOrderRepository : extends

---

部署图

容器部署

graph TB
    subgraph Host["Docker Host / VM"]
        subgraph AppContainer["App Container"]
            App["ASP.NET Core App<br/>mcr.microsoft.com/dotnet/aspnet:8.0"]
        end

        subgraph DBContainer["Database Container"]
            DB["SQL Server<br/>mcr.microsoft.com/mssql/server:2022"]
        end

        subgraph CacheContainer["Cache Container"]
            Redis["Redis<br/>redis:7-alpine"]
        end

        subgraph ReverseProxy["Reverse Proxy"]
            Nginx["Nginx<br/>(SSL termination)"]
        end
    end

    Internet["Internet"] -->|"443"| Nginx
    Nginx -->|"8080"| App
    App -->|"1433"| DB
    App -->|"6379"| Redis

Kubernetes Pod 布局

graph TB
    subgraph Cluster["Kubernetes Cluster"]
        subgraph NS["namespace: myapp"]
            subgraph Deploy1["Deployment: order-api"]
                Pod1A["Pod<br/>order-api<br/>(replica 1)"]
                Pod1B["Pod<br/>order-api<br/>(replica 2)"]
            end

            subgraph Deploy2["Deployment: catalog-api"]
                Pod2A["Pod<br/>catalog-api<br/>(replica 1)"]
            end

            SVC1["Service: order-api-svc<br/>ClusterIP:80"]
            SVC2["Service: catalog-api-svc<br/>ClusterIP:80"]
            Ingress["Ingress Controller<br/>(nginx)"]
            CM["ConfigMap:<br/>appsettings"]
            Secret["Secret:<br/>connection-strings"]
        end
    end

    Internet["Internet"] --> Ingress
    Ingress -->|"/api/orders"| SVC1
    Ingress -->|"/api/catalog"| SVC2
    SVC1 --> Pod1A
    SVC1 --> Pod1B
    SVC2 --> Pod2A
    CM -.->|"mount"| Pod1A
    CM -.->|"mount"| Pod2A
    Secret -.->|"mount"| Pod1A
    Secret -.->|"mount"| Pod2A

CI/CD 管道流程

graph LR
    subgraph Trigger
        Push["Push to main"]
        PR["Pull Request"]
        Tag["Version Tag"]
    end

    subgraph Build["Build Stage"]
        Restore["dotnet restore"]
        Compile["dotnet build"]
        Test["dotnet test"]
    end

    subgraph Package["Package Stage"]
        Pack["dotnet pack"]
        Publish["dotnet publish"]
        Docker["docker build"]
    end

    subgraph Deploy["Deploy Stage"]
        NuGet["Push to NuGet"]
        ACR["Push to ACR"]
        Staging["Deploy to Staging"]
        Prod["Deploy to Production"]
    end

    Push --> Restore
    PR --> Restore
    Tag --> Restore
    Restore --> Compile --> Test
    Test --> Pack
    Test --> Publish --> Docker
    Pack -->|"tag only"| NuGet
    Docker --> ACR
    ACR --> Staging
    Staging -->|"approval"| Prod

---

ER 图（EF Core 模型）

EF Core 关系可视化

erDiagram
    Customer ||--o{ Order : places
    Order ||--|{ OrderLine : contains
    OrderLine }o--|| Product : references
    Product }o--|| Category : "belongs to"
    Order ||--o| ShippingAddress : "ships to"
    Customer ||--o| CustomerProfile : has

    Customer {
        guid Id PK
        string Name
        string Email UK
        datetime CreatedAt
    }

    Order {
        guid Id PK
        guid CustomerId FK
        datetime OrderDate
        string Status
        decimal TotalAmount
    }

    OrderLine {
        guid Id PK
        guid OrderId FK
        guid ProductId FK
        int Quantity
        decimal UnitPrice
    }

    Product {
        guid Id PK
        guid CategoryId FK
        string Name
        string SKU UK
        decimal Price
        int StockQuantity
    }

    Category {
        guid Id PK
        string Name UK
        string Description
        guid ParentCategoryId FK "nullable, self-ref"
    }

    ShippingAddress {
        guid Id PK
        guid OrderId FK "unique"
        string Street
        string City
        string PostalCode
        string Country
    }

    CustomerProfile {
        guid Id PK
        guid CustomerId FK "unique"
        string AvatarUrl
        string Bio
    }

带索引的数据库架构

erDiagram
    AuditLog {
        long Id PK "identity"
        string EntityType "indexed"
        guid EntityId "indexed"
        string Action
        string UserId FK "indexed"
        jsonb Changes
        datetime Timestamp "indexed, default GETUTCDATE()"
    }

    SoftDeleteEntity {
        guid Id PK
        string Name
        bool IsDeleted "global query filter"
        datetime DeletedAt "nullable"
        string DeletedBy "nullable"
    }

    TenantEntity {
        guid Id PK
        guid TenantId FK "global query filter, indexed"
        string Data
    }

---

状态图

订单处理工作流

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

    Draft --> Submitted : Submit()
    Draft --> Cancelled : Cancel()

    Submitted --> PaymentPending : Process payment
    Submitted --> Cancelled : Cancel()

    PaymentPending --> PaymentFailed : Payment declined
    PaymentPending --> Paid : Payment confirmed

    PaymentFailed --> PaymentPending : Retry payment
    PaymentFailed --> Cancelled : Cancel()

    Paid --> Processing : Begin fulfillment
    Processing --> Shipped : Ship order
    Shipped --> Delivered : Confirm delivery

    Delivered --> [*]
    Cancelled --> [*]

    note right of PaymentPending
        Timeout after 30 minutes
        auto-transitions to PaymentFailed
    end note

Saga 模式（分布式事务）

stateDiagram-v2
    [*] --> OrderCreated : Start saga

    OrderCreated --> InventoryReserved : ReserveInventory
    OrderCreated --> OrderFailed : ReserveInventory failed

    InventoryReserved --> PaymentProcessed : ProcessPayment
    InventoryReserved --> InventoryReleased : ProcessPayment failed

    InventoryReleased --> OrderFailed : Compensate

    PaymentProcessed --> ShipmentScheduled : ScheduleShipment
    PaymentProcessed --> PaymentRefunded : ScheduleShipment failed

    PaymentRefunded --> InventoryReleased : Compensate

    ShipmentScheduled --> OrderCompleted : All steps succeeded
    OrderCompleted --> [*]
    OrderFailed --> [*]

    note left of InventoryReleased
        Compensation step:
        release reserved stock
    end note

    note left of PaymentRefunded
        Compensation step:
        refund payment
    end note

状态机模式（MassTransit）

stateDiagram-v2
    [*] --> New

    state "Awaiting Validation" as Validating
    state "Awaiting Payment" as AwaitingPayment
    state "Payment Failed" as PaymentFailed

    New --> Validating : OrderSubmitted event
    Validating --> AwaitingPayment : OrderValidated event
    Validating --> Cancelled : ValidationFailed event

    AwaitingPayment --> Confirmed : PaymentReceived event
    AwaitingPayment --> PaymentFailed : PaymentDeclined event

    PaymentFailed --> AwaitingPayment : PaymentRetried event
    PaymentFailed --> Cancelled : MaxRetriesExceeded

    Confirmed --> Shipped : OrderShipped event
    Shipped --> Completed : OrderDelivered event

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

---

流程图

框架选择决策树

flowchart TD
    Start["New .NET Project"] --> WebOrDesktop{"Web or Desktop?"}

    WebOrDesktop -->|"Web"| APIOnly{"API only?"}
    WebOrDesktop -->|"Desktop"| DesktopPlatform{"Target platforms?"}

    APIOnly -->|"Yes"| MinimalOrMVC{"Preference?"}
    APIOnly -->|"No, needs UI"| UIFramework{"Server or Client rendering?"}

    MinimalOrMVC -->|"Simple, few endpoints"| MinimalAPI["Minimal APIs"]
    MinimalOrMVC -->|"Complex, many controllers"| MVC["ASP.NET Core MVC/API"]

    UIFramework -->|"Server"| BlazorServer["Blazor Server / SSR"]
    UIFramework -->|"Client"| BlazorWASM["Blazor WebAssembly"]
    UIFramework -->|"Both"| BlazorAuto["Blazor Auto (SSR + WASM)"]

    DesktopPlatform -->|"Windows only"| WPFOrWinUI{"Modern UI needed?"}
    DesktopPlatform -->|"Cross-platform"| MAUI["MAUI"]

    WPFOrWinUI -->|"Legacy compat"| WPF["WPF"]
    WPFOrWinUI -->|"Modern"| WinUI["WinUI 3"]

架构决策流程图

flowchart TD
    Start["Service Design Decision"] --> Scale{"Expected scale?"}

    Scale -->|"Single team, moderate load"| Monolith["Modular Monolith"]
    Scale -->|"Multiple teams, high load"| Micro["Microservices"]

    Monolith --> MonoComm{"Communication pattern?"}
    MonoComm -->|"In-process"| MediatR["MediatR + Vertical Slices"]
    MonoComm -->|"Async events"| MonoBus["MassTransit (in-memory)"]

    Micro --> MicroComm{"Communication pattern?"}
    MicroComm -->|"Synchronous"| gRPC["gRPC / REST"]
    MicroComm -->|"Asynchronous"| MsgBus["Message Bus<br/>(RabbitMQ / Azure SB)"]
    MicroComm -->|"Both"| Hybrid["gRPC + Message Bus"]

    Micro --> DataStrategy{"Data strategy?"}
    DataStrategy -->|"Shared DB"| SharedDB["Shared Database<br/>(simpler, less isolation)"]
    DataStrategy -->|"DB per service"| OwnDB["Database per Service<br/>(more isolation, eventual consistency)"]

---

图表即代码约定

命名约定

• 节点 ID 使用 PascalCase：OrderService、CustomerDB
• 使用带有技术信息的描述性标签：API["Order API<br/>(ASP.NET Core)"]
• 使用一致的缩写：DB（数据库）、API（端点）、SVC（服务）、MQ（消息队列）
• 子图前缀使用层或层级名称：subgraph DataTier["Data Tier"]

分组模式

• 按架构层分组（Presentation、Application、Domain、Infrastructure）
• 按部署边界分组（容器、Pod、VM）
• 在微服务图中按团队归属分组
• 使用子图进行可视化分组——为保证可读性，嵌套层级最多为 2 层

GitHub 渲染技巧

• 在 Markdown 文件、议题、PR 和讨论中，GitHub 会将带有 mermaid 语言标识符的围栏代码块渲染为 Mermaid 图表
• 建议的图表最大尺寸：约 50 个节点，以确保渲染结果清晰易读
• GitHub 默认使用浅色主题——避免使用在白色背景上会消失的浅色填充
• 图表会自动调整到容器宽度——保持节点标签简洁（每行少于 30 个字符）
• 在节点标签中使用 <br/> 换行（不要使用 \n）
• 合并前在 GitHub 上测试图表——语法错误会以原始文本形式显示

深色模式注意事项

• 避免使用在深色模式下显示异常的硬编码颜色——尽可能使用 Mermaid 主题变量
• Mermaid 默认颜色在 GitHub 的浅色和深色主题下均可正常显示
• 如果使用自定义 style 指令，请在 GitHub 的浅色和深色模式下都进行测试
• 为便于维护，优先使用语义化的 classDef 样式，而非内联 style：

%%{init: {'theme': 'neutral'}}%%
graph LR
    A["Service A"] --> B["Service B"]
    A --> C["Service C"]

    classDef healthy fill:#4caf50,color:#fff
    classDef degraded fill:#ff9800,color:#fff
    class A healthy
    class B degraded
    class C healthy

• neutral 主题在 GitHub 上的跨主题兼容性最佳
• 对于文档站点（Starlight、Docusaurus），主题由平台的 CSS 控制——Mermaid 会自动继承

图表尺寸指南

图表类型	建议的最大节点数	备注
C4 上下文图	10-12	一个系统 + 外部参与者
C4 容器图	15-20	内部容器 + 数据存储
C4 组件图	15-20	单个服务的内部结构
序列图	8 个参与者	更多参与者会导致图表难以阅读
类图	10-15 个类	拆分为多个图表
ER 图	10-12 个实体	按限界上下文拆分
状态图	12-15 个状态	将复杂工作流拆分
流程图	15-20 个节点	保持决策树重点明确

---

Agent 注意事项

1. 始终在图表中使用 .NET-specific content——不要生成通用图表。使用真实的 .NET 类型（DbContext、IRepository、MediatR）、真实的 .NET 工具（EF Core、MassTransit、YARP）和真实的 .NET 模式（中间件管道、DI 注册）。

2. 图表节点数控制在 50 个以内——节点过多会导致图表在 GitHub 和文档站点上显示效果不佳。将复杂架构拆分为多个重点明确的图表（上下文、容器、组件），而不是绘制一个庞大的图表。

3. 在节点标签中使用 <br/> 换行，不要使用 \n——Mermaid 会将 \n 按原样渲染为文本。多行标签需要使用 <br/> HTML 标签。

4. 提交前测试 Mermaid 语法——语法错误会导致 GitHub 显示原始文本，而不是图表。请使用 Mermaid Live Editor（https://mermaid.live）或本地预览工具进行验证。

5. ER 图的关系表示法遵循 Mermaid 语法，而非 UML——一对多使用 ||--o{，一对一使用 ||--||。不要使用 UML 多重性表示法。

6. 使用 neutral 主题以确保与 GitHub 兼容——%%{init: {'theme': 'neutral'}}%% 在浅色和深色模式下都能提供最佳渲染效果。

7. 时序图的参与者名称不能包含特殊字符——名称中包含空格或特殊字符时，请使用 participant DB as "SQL Server" 别名语法。

8. 嵌套泛型（Task~List~T~~）可能无法在所有 Mermaid 版本中正确渲染——嵌套泛型类型末尾的双 ~~ 需要 Mermaid v10.3+。提交复杂泛型类型图表前，请在目标环境中测试渲染效果。

9. 不要在面向 GitHub 的图表中使用 Font Awesome 图标语法（fa:fa-user）——GitHub 的原生 Mermaid 渲染器不会加载 Font Awesome CSS。图标会按原样显示为文本。请改用纯文本标签。

10. 不要在文档平台中配置 Mermaid 渲染——平台配置（Starlight remark 插件、Docusaurus 主题、DocFX 模板）属于 [skill:dotnet-documentation-strategy]。本技能仅提供图表内容。