⚡

C4模型架构文档技能Skill c4-documentation

该技能用于基于C4模型创建软件架构文档，涵盖系统上下文、容器、组件和代码四个抽象级别，支持架构可视化和文档化。关键词：C4模型、架构设计、文档化、软件架构、可视化、系统上下文图、容器图、组件图。

架构设计 0 次安装 0 次浏览 更新于 3/11/2026

name: c4-documentation description: C4 模型架构可视化和文档化 allowed-tools: 读取, 全局搜索, 查找, 写入, 编辑

C4 文档技能

使用 C4 模型的四个抽象级别创建架构文档。

强制要求：文档优先方法

在创建 C4 文档之前：

  1. 调用 docs-management 技能 获取 C4 模式
  2. 通过 MCP 服务器验证 C4 模型语法（使用 context7 用于 Structurizr/Mermaid）
  3. 基于 c4model.com 官方文档 提供指导

C4 模型概述

C4 模型 - 四个抽象级别：

级别 1：系统上下文
┌─────────────────────────────────────────────────────────────────────────────┐
│  显示系统在用户和外部系统中的上下文                                       │
│  受众：所有人（技术人员和非技术人员）                                     │
└─────────────────────────────────────────────────────────────────────────────┘
                                    ↓
级别 2：容器
┌─────────────────────────────────────────────────────────────────────────────┐
│  显示高层次的技术选择和职责                                               │
│  受众：技术人员（团队内外）                                               │
└─────────────────────────────────────────────────────────────────────────────┘
                                    ↓
级别 3：组件
┌─────────────────────────────────────────────────────────────────────────────┐
│  显示容器内的组件                                                         │
│  受众：软件架构师和开发者                                                 │
└─────────────────────────────────────────────────────────────────────────────┘
                                    ↓
级别 4：代码（可选）
┌─────────────────────────────────────────────────────────────────────────────┐
│  显示类、接口和实现细节                                                   │
│  受众：开发者（通常自动生成）                                             │
└─────────────────────────────────────────────────────────────────────────────┘

级别 1：系统上下文图

目的

显示软件系统在以下上下文中的情况：

  • 谁使用它（人员）
  • 它与哪些其他系统交互

Mermaid 语法

C4Context
    title 系统上下文图 for [系统名称]

    Person(客户, "客户", "使用我们平台的客户")
    Person(管理员, "管理员", "系统管理员")

    System(系统, "系统名称", "允许客户执行 X 和 Y")

    System_Ext(邮件, "邮件系统", "发送事务性邮件")
    System_Ext(支付, "支付网关", "处理支付")
    System_Ext(分析, "分析平台", "跟踪用户行为")

    Rel(客户, 系统, "使用", "HTTPS")
    Rel(管理员, 系统, "管理", "HTTPS")
    Rel(系统, 邮件, "使用发送邮件", "SMTP")
    Rel(系统, 支付, "通过处理支付", "HTTPS/REST")
    Rel(系统, 分析, "发送事件到", "HTTPS")

PlantUML/Structurizr DSL

@startuml
!include <C4/C4_Context>

title 系统上下文图 for [系统名称]

Person(客户, "客户", "使用我们平台的客户")
Person(管理员, "管理员", "系统管理员")

System(系统, "系统名称", "允许客户执行 X 和 Y")

System_Ext(邮件, "邮件系统", "发送事务性邮件")
System_Ext(支付, "支付网关", "处理支付")

Rel(客户, 系统, "使用", "HTTPS")
Rel(管理员, 系统, "管理", "HTTPS")
Rel(系统, 邮件, "使用发送邮件", "SMTP")
Rel(系统, 支付, "通过处理支付", "HTTPS")

@enduml

级别 2：容器图

目的

显示软件架构的高层次形状：

  • 应用程序、数据存储、微服务
  • 它们如何通信
  • 技术选择

Mermaid 语法

C4Container
    title 容器图 for [系统名称]

    Person(客户, "客户", "最终用户")

    System_Boundary(系统, "系统名称") {
        Container(网页应用, "网页应用程序", "Blazor", "交付用户界面")
        Container(api网关, "API 网关", "Kong", "路由和保护 API")
        Container(订单服务, "订单服务", ".NET 10", "处理订单处理")
        Container(库存服务, "库存服务", ".NET 10", "管理库存")
        ContainerDb(数据库, "数据库", "PostgreSQL", "存储订单和库存")
        ContainerQueue(消息代理, "消息代理", "Kafka", "异步消息传递")
    }

    Rel(客户, 网页应用, "使用", "HTTPS")
    Rel(网页应用, api网关, "进行 API 调用", "HTTPS/JSON")
    Rel(api网关, 订单服务, "路由到", "gRPC")
    Rel(api网关, 库存服务, "路由到", "gRPC")
    Rel(订单服务, 数据库, "读取/写入", "TCP")
    Rel(库存服务, 数据库, "读取/写入", "TCP")
    Rel(订单服务, 消息代理, "发布事件", "Kafka 协议")
    Rel(库存服务, 消息代理, "订阅事件", "Kafka 协议")

容器类型

类型 用途 示例
Container 应用程序/服务 API、网页应用、微服务
ContainerDb 数据库 PostgreSQL、MongoDB、Redis
ContainerQueue 消息队列 Kafka、RabbitMQ、SQS
Container_Ext 外部容器 托管在别处的第三方 API

级别 3：组件图

目的

显示容器的内部结构：

  • 主要组件及其职责
  • 组件之间的交互
  • 技术实现

Mermaid 语法

C4Component
    title 订单服务的组件图

    Container_Boundary(订单服务, "订单服务") {
        Component(api控制器, "API 控制器", ".NET", "处理 HTTP 请求")
        Component(命令处理器, "命令处理器", "MediatR", "处理命令")
        Component(领域模型, "领域模型", "C#", "业务逻辑和规则")
        Component(仓库, "仓库", "EF Core", "数据访问抽象")
        Component(事件发布者, "事件发布者", "MassTransit", "发布领域事件")
    }

    ContainerDb(数据库, "数据库", "PostgreSQL", "存储订单数据")
    ContainerQueue(消息代理, "消息代理", "Kafka", "事件传输")

    Rel(api控制器, 命令处理器, "分派到")
    Rel(命令处理器, 领域模型, "使用")
    Rel(命令处理器, 仓库, "使用")
    Rel(命令处理器, 事件发布者, "通过发布")
    Rel(仓库, 数据库, "读取/写入")
    Rel(事件发布者, 消息代理, "发布到")

级别 4：代码图

目的

显示实现细节（通常自动生成）：

  • 类图
  • 实体关系
  • 接口定义

使用时机

  • 复杂领域模型
  • 框架文档
  • 公共 API 文档
classDiagram
    class 订单 {
        +Guid Id
        +Guid 客户Id
        +OrderStatus 状态
        +IReadOnlyList~LineItem~ 项目
        +Money 总计
        +添加项目(产品, int)
        +提交()
        +取消()
    }

    class 订单项目 {
        +Guid 产品Id
        +string 产品名称
        +int 数量
        +Money 单价
        +Money 总计
    }

    class 订单状态 {
        <<枚举>>
        草稿
        已提交
        已确认
        已发货
        已交付
        已取消
    }

    订单 "1" *-- "*" 订单项目
    订单 --> 订单状态

补充图

部署图

C4Deployment
    title 生产部署图

    Deployment_Node(azure云, "Azure 云", "云平台") {
        Deployment_Node(区域, "东部美国", "Azure 区域") {
            Deployment_Node(aks集群, "AKS 集群", "Kubernetes 1.28") {
                Deployment_Node(命名空间, "生产命名空间") {
                    Container(api, "API Pods", "3 副本")
                    Container(工作器, "工作器 Pods", "2 副本")
                }
            }
            Deployment_Node(数据服务, "数据服务") {
                ContainerDb(数据库, "Azure PostgreSQL", "灵活服务器")
                ContainerDb(redis, "Azure Redis", "高级层")
            }
        }
    }

    Rel(api, 数据库, "连接到", "TCP/5432")
    Rel(api, redis, "缓存使用", "TCP/6379")

动态图（序列图）

sequenceDiagram
    participant U as 用户
    participant W as 网页应用
    participant A as API 网关
    participant O as 订单服务
    participant D as 数据库

    U->>W: 点击“下单”
    W->>A: POST /api/orders
    A->>O: 创建订单
    O->>D: INSERT 订单
    D-->>O: 订单已创建
    O-->>A: 订单已创建
    A-->>W: 201 已创建
    W-->>U: 订单确认

C4 文档模板

# C4 架构文档: [系统名称]

## 1. 系统上下文

### 图

[级别 1 上下文图]

### 描述

[解释上下文的叙述]

### 参与者和外部系统

| 元素 | 类型 | 描述 |
|---------|------|-------------|
| [名称] | 人员 | [描述] |
| [名称] | 外部系统 | [描述] |

---

## 2. 容器视图

### 图

[级别 2 容器图]

### 容器目录

| 容器 | 技术 | 职责 |
|-----------|------------|----------------|
| [名称] | [技术] | [它做什么] |

---

## 3. 组件视图

### 3.1 [容器名称] 组件

#### 图

[级别 3 组件图]

#### 组件目录

| 组件 | 技术 | 职责 |
|-----------|------------|----------------|
| [名称] | [技术] | [它做什么] |

---

## 4. 部署视图

### 图

[部署图]

### 基础设施元素

| 元素 | 技术 | 目的 |
|---------|------------|---------|
| [名称] | [技术] | [目的] |

---

## 5. 关键场景

### 5.1 [场景名称]

[动态/序列图]

[叙述描述]

C# C4 元素模型

// C4 模型元素
public abstract record C4元素
{
    public required string Id { get; init; }
    public required string 名称 { get; init; }
    public string? 描述 { get; init; }
    public string? 技术 { get; init; }
}

public sealed record 人员 : C4元素
{
    public string? 角色 { get; init; }
}

public sealed record 软件系统 : C4元素
{
    public bool 是否外部 { get; init; }
    public IReadOnlyList<容器> 容器 { get; init; } = [];
}

public sealed record 容器 : C4元素
{
    public required 容器类型 类型 { get; init; }
    public IReadOnlyList<组件> 组件 { get; init; } = [];
}

public enum 容器类型
{
    网页应用程序,
    移动应用,
    桌面应用,
    服务,
    数据库,
    文件系统,
    消息代理,
    缓存
}

public sealed record 组件 : C4元素
{
    public string? 接口 { get; init; }
}

public sealed record 关系
{
    public required string 源Id { get; init; }
    public required string 目标Id { get; init; }
    public required string 描述 { get; init; }
    public string? 技术 { get; init; }
}

// C4 图生成器
public interface IC4图生成器
{
    string 生成上下文图(
        软件系统 系统,
        IEnumerable<人员> 人员,
        IEnumerable<软件系统> 外部系统,
        IEnumerable<关系> 关系);

    string 生成容器图(
        软件系统 系统,
        IEnumerable<关系> 关系);

    string 生成组件图(
        容器 容器,
        IEnumerable<关系> 关系);
}

最佳实践

应该做的

  • 保持图简单且专注
  • 使用一致的符号和颜色
  • 需要时包括图例
  • 架构变化时更新图
  • 尽可能使用自动生成

不应该做的

  • 不要在每个图上显示每个组件
  • 不要混合抽象级别
  • 不要忘记叙述描述
  • 不要创建从不更新的图

工作流

创建 C4 文档时：

  1. 从上下文开始：级别 1 显示大局
  2. 放大到容器：级别 2 显示技术选择
  3. 按需详细说明：级别 3 用于复杂容器
  4. 添加场景：动态图用于关键流程
  5. 包括部署：显示基础设施映射
  6. 保持最新：保持图与代码同步

参考

详细指导请参考：

最后更新: 2025-12-26