C4 图
来源:官方C4模型:https://c4model.com/。每当你绘制、审查或解释C4图时,请应用这些规则。当输出包含散文(ADR、文档、PR描述)时,同时加载`writing`技能。
1. 目的
C4是一组“代码地图”,有四个缩放级别:上下文、容器、组件和代码。Simon Brown受UML和4+1视图模型启发创建了它,旨在取代随意绘制的方框和线条图。它修复的典型问题:没有图例、抽象层次混杂、未标注的箭头、缺少技术细节、以及诸如“业务逻辑”之类的模糊标签。
C4独立于符号和工具。下面的抽象层次和规则才是重要的,形状并不重要。
2. 抽象层次
层次结构:人员 -> 软件系统 -> 容器 -> 组件 -> 代码。每个级别都放大上一级别的某个元素。
| 抽象层次 | 定义 | 示例 |
|---|---|---|
| 人员 | 系统的人类用户、参与者、角色或用户画像 | 客户、客服、管理员 |
| 软件系统 | 最高级别的抽象;为用户提供价值。通常由一个团队拥有和构建。它不是产品域、限界上下文、部落或小队 | 票务平台、支付系统 |
| 容器 | 软件系统内可独立运行/部署的应用程序或数据存储 | 服务器端Web应用、SPA、桌面应用、移动应用、无服务器函数、批处理/控制台应用、微服务API、数据库模式、S3/Blob存储、CDN、文件系统、Shell脚本 |
| 组件 | 容器内部通过定义良好的接口组织在一起的相关功能集合。不可单独部署:容器的所有组件共享一个进程空间 | OrderController、PaymentService、EmailSender |
| 代码 | 组件内部的类、接口、函数或数据库表 | class OrderValidator、orders表 |
容器规则(C4常见问题解答)
- C4中的容器不是Docker容器。 它是指可运行/可部署的应用程序或数据存储,无论其打包方式如何。
- 一个服务器端渲染的HTML应用是1个容器。一个服务器加上一个SPA或移动客户端是2个通过远程API通信的容器。
- JAR、DLL、程序集和模块不是容器。它们用于组织容器内的代码。
- 当你拥有或控制存储桶或模式时,受管数据服务(S3、RDS、CDN)是系统边界内的容器。它们不是外部系统。
组件规则
- 组件不是文件夹、包或JAR。它是一个具有接口的功能分组。
- 组件不可独立部署。如果可以单独部署,那它就是容器。
术语适配
团队可以在图中或文档中明确定义后,使用语言惯用的名称(例如函数式代码中的Module或Function)。除非每个级别都有严格定义,否则不要发明额外的抽象级别。
3. 特殊建模模式
队列和主题
- 错误做法: 在中部放置一个巨大的“消息总线”容器,连接所有服务(星型拓扑)。这掩盖了谁生产和谁消费。
- 选项1(推荐): 将每个队列或主题建模为独立的容器(消息数据存储)。生产者写入,消费者读取或订阅。
- 选项2: 对于直接的端到端耦合,省略队列框,并将关系标记为
"Publishes order events via Queue orders [AMQP]"。可选择将这些线条与HTTP调用的样式不同(在图例中说明)。
例如:Order API --"将OrderPlaced发布到[Kafka]"--> [(orders topic)] --"从[Kafka]读取OrderPlaced"--> Fulfilment Worker。
微服务(康威定律规则)
- 一个团队拥有整个软件系统: 将每个微服务建模为该系统边界内的一组容器(API容器及其自身数据库模式容器,或单个无状态Lambda容器)。
- 独立团队拥有各自的服务: 将每个独立拥有的服务提升为独立的软件系统,每个系统都有各自的系统上下文图和容器图。在跨系统边界时明确说明队列/主题的所有权。
4. 图目录
核心静态级别
| 级别 | 图 | 推荐 | 范围 | 受众 | 显示/省略 |
|---|---|---|---|---|---|
| 1 | 系统上下文 | 是 | 1个软件系统 | 技术人员与非技术人员 | 系统周围的人员和外部系统。省略低级技术和协议。 |
| 2 | 容器 | 是 | 1个软件系统 | 技术人员、运维人员 | 主要技术选择和进程间协议。省略集群、负载均衡器、故障转移。 |
| 3 | 组件 | 否:只有在能明确增加价值且最好自动生成时才使用 | 1个容器 | 架构师、开发人员 | 一个容器内部的组件及其交互。 |
| 4 | 代码 | 否:按需在IDE中生成 | 1个组件 | 开发人员 | UML类图或ER图。 |
补充图
| 图 | 推荐 | 用途 |
|---|---|---|
| 系统景观图 | 是,用于组织和项目组合 | 所有系统和人员的企业或部门地图。一个没有单一焦点系统的上下文图。 |
| 动态图 | 否:谨慎使用 | 复杂的运行时协作。使用编号协作风格或UML序列风格。 |
| 部署图 | 是 | 1个环境(生产、预发布、开发)。嵌套的部署节点(物理、VM、Docker、Kubernetes、运行时)包含系统/容器实例,以及基础设施节点(DNS、负载均衡器、防火墙)。 |
兼容性
- arc42: 上下文与范围 -> L1;构建块级别1 -> L2;构建块级别2 -> L3;构建块级别3 -> L4。
- UML: 使用UML状态图、序列图和ER图来补充C4,用于工作流、状态机和数据模型。
缩放规则
当图表变得杂乱时,不要在一个画布上塞满几十个框。在相同的抽象级别上按业务领域、限界上下文、功能或单一服务焦点(焦点服务及其入站和出站邻居)进行拆分。
5. 符号规则
图
- 标题指明图表类型和范围:
Checkout System的容器图。 - 始终包含解释形状、颜色、边框、线条类型、箭头和缩写的图例/说明。
- 保持严格的抽象纯度:永远不要混合抽象级别(例如,在L2容器图中不要出现
Component框),永远不要在L1系统上下文图中放置协议或内部实现步骤([HTTPS]、masked packet、tool_runner)。 - 在比较竞争或历史架构时,明确标注边界标题(
选项A(已淘汰)vs.选项B(当前)),并在需求或假设发生变化时更新文档中的所有图表。
元素
- 名称、明确的元素类型(
Person、Software System、Container、Component、Database、Deployment Node)以及简洁的职责描述。 - 每个容器、组件和部署节点上都要明确标注技术。
关系
- 仅使用单向箭头。 绝不用
<-->。如果数据双向流动,显示发起方的方向,并在标签中描述响应。 - 使用具体的主动动词标签。从不使用赤裸裸的“使用”。写为
向...提交订单、从...读取座位图。 - 在容器到容器关系上标注协议/技术:
[JSON/HTTPS]、[SQL]、[gRPC]、[AMQP]。
6. Markdown中的Mermaid
默认使用flowchart(flowchart TB或LR),而不是Mermaid原生C4Context/C4Container。原生的C4语法是实验性的,通常在Markdown查看器中渲染失败。仅在用户明确要求并确认渲染器支持时才使用它。
Flowchart约定:
- 使用
subgraph表示系统边界(容器/组件)或部署节点。 - 使用
[(...)]表示数据库、数据存储、队列和主题。 - 带引号的HTML标签:
"<b>Name</b><br/>«Container: Tech»<br/>Short responsibility"。 - 带引号标签的箭头:
A -->|"Action [Protocol]"| B。 - 每种元素类型一个
classDef,并一致应用。 - 一个紧凑的
Legend子图(未连接的节点,使用不可见的bottomNode ~~~ Legend链接锚定在底部,当Dagre将其放在顶部时)在使用颜色、圆柱形状或多线条样式时是必需的;将标题作为标题或Title: ...行直接放在代码块上方。 - 动态图:
sequenceDiagram,或使用带有编号箭头标签(1. Submits order [JSON/HTTPS])的flowchart。 - 部署图:
flowchart中的嵌套subgraph。 - 始终引用包含括号、方括号或冒号的标签。
- 绝对不要在
sequenceDiagram或stateDiagram-v2标签中放置未转义的分号(;)(Mermaid将;视为语句终止符,并将剩余文本拆分为虚假状态或解析错误);使用<br/>包裹sequenceDiagram中的长Note块,以免文本在视口边缘被裁剪。
模板:L1 系统上下文
标题:票务平台的系统上下文图
flowchart TB
customer["<b>Customer</b><br/>«Person»<br/>Buys tickets for events"]
ticketing["<b>Ticketing Platform</b><br/>«Software System»<br/>Lets customers browse events and buy tickets"]
payments["<b>Payment Provider</b><br/>«Software System, external»<br/>Charges cards"]
email["<b>Email Service</b><br/>«Software System, external»<br/>Delivers confirmation emails"]
customer -->|"Browses events and buys tickets using"| ticketing
ticketing -->|"Requests card charges from"| payments
ticketing -->|"Sends confirmation emails using"| email
email -->|"Delivers confirmation emails to"| customer
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef system fill:#1168bd,stroke:#0b4884,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class customer person
class ticketing system
class payments,email external
subgraph Legend
direction LR
l1["Person"]:::person
l2["Software System (in scope)"]:::system
l3["Software System (external)"]:::external
end
模板:L2 容器(带队列容器)
标题:票务平台的容器图
flowchart TB
customer["<b>Customer</b><br/>«Person»<br/>Buys tickets for events"]
payments["<b>Payment Provider</b><br/>«Software System, external»<br/>Charges cards"]
subgraph boundary["Ticketing Platform [Software System]"]
spa["<b>Web App</b><br/>«Container: React SPA»<br/>Event browsing and checkout UI"]
api["<b>Order API</b><br/>«Container: Java, Spring Boot»<br/>Validates and places orders"]
db[("<b>Orders DB</b><br/>«Container: PostgreSQL»<br/>Stores orders and tickets")]
topic[("<b>orders topic</b><br/>«Container: Kafka topic»<br/>OrderPlaced events")]
worker["<b>Fulfilment Worker</b><br/>«Container: Python»<br/>Issues tickets and sends emails"]
end
customer -->|"Browses and buys using [HTTPS]"| spa
spa -->|"Submits orders to [JSON/HTTPS]"| api
api -->|"Writes orders to [SQL/TCP]"| db
api -->|"Publishes OrderPlaced to [Kafka]"| topic
worker -->|"Reads OrderPlaced from [Kafka]"| topic
worker -->|"Updates ticket status in [SQL/TCP]"| db
api -->|"Requests card charges from [JSON/HTTPS]"| payments
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef container fill:#438dd5,stroke:#2e6295,color:#fff
classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class customer person
class spa,api,worker container
class db,topic store
class payments external
subgraph Legend
direction LR
l1["Person"]:::person
l2["Container"]:::container
l3[("Data store / queue / topic")]:::store
l4["External system"]:::external
end
图例说明:箭头从发起方指向目标。标签说明操作和[协议]。
模板:部署图
标题:票务平台的部署图(生产环境)
flowchart TB
users["<b>Customer browser</b><br/>«Deployment Node: Chrome»"]
subgraph aws["AWS «Deployment Node: Cloud, us-east-1»"]
dns["<b>Route 53</b><br/>«Infrastructure Node: DNS»"]
lb["<b>Load Balancer</b><br/>«Infrastructure Node: ALB»"]
subgraph eks["EKS «Deployment Node: Kubernetes cluster»"]
subgraph pod["order-api pod «Deployment Node: Docker, x3»"]
api["<b>Order API</b><br/>«Container instance: Java, Spring Boot»"]
end
end
subgraph rds["RDS «Deployment Node: PostgreSQL 16»"]
db[("<b>Orders DB</b><br/>«Container instance: PostgreSQL schema»")]
end
end
users -->|"Resolves hostname using [DNS]"| dns
users -->|"Sends requests to [HTTPS]"| lb
lb -->|"Forwards requests to [HTTP]"| api
api -->|"Reads and writes orders in [SQL/TCP]"| db
如果使用默认样式以外的颜色或样式,请添加图例子图。
模板:动态图(序列图)
标题:票务平台订单结账的动态图(序列样式)
sequenceDiagram
autonumber
actor customer as Customer
participant spa as Web App (React SPA)
participant api as Order API (Spring Boot)
participant payments as Payment Provider
participant db as Orders DB (PostgreSQL)
participant topic as orders topic (Kafka)
customer->>spa: Clicks "Place Order"
spa->>api: POST /orders [JSON/HTTPS]
api->>payments: Charges card [JSON/HTTPS]
payments-->>api: Payment authorized
api->>db: Inserts order row [SQL/TCP]
api->>topic: Publishes OrderPlaced [Kafka]
api-->>spa: 201 Created (order confirmation)
spa-->>customer: Shows order receipt
保持sequenceDiagram参与者和消息标签中不含未转义的斜杠、分号(;,Mermaid将其解析为语句终止符)或原始换行符,以获得最佳的Markdown查看器兼容性。
7. Diagr
…
[翻译截断]