软件架构本质上是复杂的。随着系统规模的扩大，理解它们所需的思维模型呈指数级增长。如果没有结构化的方法，开发人员、利益相关者和架构师之间的沟通就会崩溃。C4 模型提供了一种标准化的方式来通过图表层级可视化软件架构。本指南将引导你创建第一个 C4 图表，重点关注清晰度、受众和意图。
C4 模型并非一个僵化的标准，而是一个灵活的框架。它被开发出来，旨在帮助团队有效地沟通软件的结构。通过将架构分解为四个不同的层级，你可以在必要时才深入细节。本教程专注于这些概念的实际应用，确保你创建的图表传达意义，而不仅仅是技术规格。
🧩 理解四个层级
C4 模型的核心在于其四个层级结构。每个层级服务于不同的受众，并回答特定的一组问题。从第 1 层到第 4 层的转换，代表从高层次的上下文转向细致的实现细节。
在创建图表时，清楚自己正在绘制的是哪一层级至关重要。混淆层级，或在错误的时间绘制过多细节，都会导致混乱。以下是各阶段范围和目的的详细说明。
| 层级 | 图表名称 | 主要受众 | 核心问题 |
|---|---|---|---|
| 1 | 系统上下文 | 所有人（利益相关者、开发人员） | 这个系统是什么？谁在使用它？ |
| 2 | 容器 | 开发人员、架构师 | 系统是如何构建的？ |
| 3 | 组件 | 开发人员 | 软件内部是如何结构化的？ |
| 4 | 代码 | 开发人员 | 类之间如何交互？ |
第 1 层：系统上下文图
这是任何架构可视化工作的起点。它提供了所讨论软件系统的全局视角。目标是将系统呈现为一个单一的黑箱，并展示其与外部世界的关系。
- 范围： 整个应用程序或服务。
- 元素：人员、角色和外部系统。
- 连接：数据流或交互协议。
绘制此图时，避免使用技术术语。专注于业务价值和交互。系统上下文图回答的问题是：“它在这个生态系统中处于什么位置？”
层级 2：容器图
确定上下文后，你将进行放大。容器代表一个独立的运行时环境，是一个物理部署单元，例如 Web 应用、移动应用、数据库或微服务。
- 范围：系统的内部结构。
- 元素：如 Node.js、PostgreSQL、Angular 或 AWS Lambda 等技术。
- 连接：如 HTTP、TCP 或 SQL 等协议。
这一层级弥合了业务需求与技术实现之间的差距。它帮助开发人员理解数据存储的位置以及服务之间的通信方式，而无需深入代码细节。
层级 3：组件图
容器内部包含组件。这些是功能的逻辑分组，它们不是物理文件，而是软件内部的概念边界。
- 范围：容器内的特定功能。
- 元素：执行特定任务的模块、库或类。
- 连接：API 调用、方法调用或内部消息传递。
组件图在新开发人员入职或重构代码库特定部分时最有用。它们展示了职责是如何划分的。
层级 4：代码图
这一层级涉及类图和内部逻辑。尽管通常由开发工具自动生成，但在 C4 过程中很少手动绘制。它过于细致，不适合大多数架构讨论。
🛠️ 为首次会议做准备
在打开任何绘图软件之前，准备工作至关重要。没有计划就匆忙开始绘制，往往会导致画面杂乱且令人困惑。遵循以下准备步骤，以确保流程顺畅。
- 明确目标：你为什么要创建这张图？是为了入职培训、文档编写，还是规划迁移？
- 确定受众： 谁会阅读这个？高管需要第1级。开发人员需要第2级和第3级。
- 收集信息： 与团队交谈。了解系统的当前状态。审查现有文档。
- 选择工具： 选择一个支持C4标准所需形状和连接线的绘图应用程序。
记住，这些图表是动态文档。它们应随着系统的演进而演变。不要将它们视为一次性产物。
🌍 创建你的第一个系统上下文图
第1级是基础。如果没有清晰的上下文，架构的其余部分就会缺乏视角。以下是构建此图的逐步方法。
步骤1：定义系统边界
画一个方框来表示你正在记录的软件系统。用应用程序的名称清晰地标记这个方框。确保名称与团队在日常对话中使用的名称一致。
- 使用一个简单的矩形。
- 将名称放在中心。
- 此处不要包含内部细节。
步骤2：识别人员和角色
谁与这个系统交互？通常是最终用户、管理员或外部服务。
- 用人形图表示人类用户。
- 用他们的角色标签（例如，“客户”、“管理员”、“支持团队”）进行标注。
- 如果用户很多，将相似的用户分组。
步骤3：识别外部系统
这个系统与其他哪些软件通信？可能是支付网关、电子邮件服务或遗留数据库。
- 使用标准方框表示软件系统。
- 用它们的功能进行标注（例如，“支付提供商”、“CRM”）。
- 标明它们是内部还是外部的。
步骤4：绘制连接
画线将人员和外部系统连接到你的主系统方框。这些线代表数据流。
- 用数据类型或操作类型对线条进行标注（例如，“下单”、“发送邮件”）。
- 使用箭头表示数据流的方向。
- 保持线条笔直或正交，以减少视觉干扰。
与非技术利益相关者一起审查该图。如果他们理解了流程，你就成功了。
📦 创建你的第一个容器图
一旦上下文清晰，你就需要展示系统的构建方式。这需要将第1级的主要系统框分解为更小的运行时单元。
步骤1：列出容器
识别运行应用程序的不同技术。一个典型的Web应用程序可能包含Web服务器、移动应用和数据库。
- 为每个容器绘制方框。
- 用技术名称标注它们（例如：“React应用”、“PostgreSQL”）。
- 如果容器共享部署边界，则将它们分组。
步骤2：定义关系
连接容器以展示它们如何交互。这些连接应反映运行时架构。
- 使用箭头表示请求的方向。
- 标注协议（例如：“HTTPS”、“REST API”）。
- 此阶段避免展示数据实体；应专注于基础设施。
步骤3：添加上下文说明
为复杂容器添加简要描述。如果某个容器有特定的安全要求或性能限制，请简要注明。
- 保持注释简洁。
- 用它们来突出关键的架构决策。
- 确保图表保持可读性。
该图表有助于开发人员理解部署拓扑。这对于DevOps和基础设施规划至关重要。
⚙️ 创建你的第一个组件图
第3级深入探讨逻辑。在这里，你需要解释软件内部如何工作。这一级别通常最为详细，需要仔细组织。
步骤1：选择一个容器
一次专注于一个容器。在此级别不要试图绘制整个系统。选择最复杂或最关键的容器。
- 将范围限定为第2级的一个方框。
- 这可以防止图表变得过于复杂。
步骤2：识别职责
将容器分解为功能区域。这些就是组件。
- 按职责对类或模块进行分组（例如：“用户服务”、“订单处理器”）。
- 使用圆角矩形表示组件。
- 保持名称具有描述性且面向业务。
步骤3：映射交互
展示组件之间如何通信。这包括API调用、事件监听器或数据传递。
- 在组件之间绘制连线。
- 标记被调用的接口或方法。
- 确保控制流清晰。
步骤4：避免过度设计
不要绘制每一个类。专注于高层次结构。如果某个组件过于复杂，可考虑为其创建子图。
- 使用层级结构来管理复杂性。
- 隐藏不影响整体架构的实现细节。
🔄 维护与演进
只有准确的图表才有用。随着时间推移，软件会发生变化，图表可能变得过时。维护它们需要纪律和策略。
- 变更时更新： 如果发生重大架构变更，应立即更新图表。
- 定期审查： 在冲刺计划或架构回顾期间安排定期审查。
- 保持简洁： 移除已弃用的元素。不要用历史数据使图表杂乱。
- 版本控制： 将图表文件与代码存储在同一个仓库中。这可以确保可追溯性。
常见的陷阱包括绘制过于详细的图表，或完全不进行文档记录。目标是保持平衡。一个80%准确且易于阅读的图表，比一个100%准确却无人能懂的图表更好。
应避免的常见错误
在创建你的第一个图表时，请注意这些常见错误。
- 层级混淆： 将组件的细节放入系统上下文图中。
- 缺少标签： 绘制连线但未说明其传递的内容。
- 颜色过多： 使用颜色进行装饰而非表达意义。
- 忽视受众： 为高管利益相关者创建三级图表。
- 仅静态视图： 仅关注结构，而忽略数据流或行为。
📝 最终思考
掌握建筑可视化艺术需要练习。C4模型提供了一条通往清晰的结构化路径。从系统上下文开始，逐步深入，你就能构建出一个叙事，引导你的受众理解软件的复杂性。
请记住，图表是一种沟通工具，而不是设计约束。它们应有助于理解，而不是限制创造力。随着你不断磨练技能，你会发现绘制图表的过程常常会暴露出你对系统理解中的盲点。
从小处着手。记录一个系统。优化流程。随着时间推移，这些图表将成为团队不可或缺的资产，减少入职时间并降低误解。你现在投入创建这些视觉内容的努力，将在未来带来清晰度和协作上的回报。
