C4 架构图与架构文档

用 Mermaid 生成 C4 上下文、容器、组件、代码架构图。

核心认识

使用 Simon Brown 的 C4 模型，以 Context、Container、Component、Code 四层视图说明软件架构。输入可以是讨论、设计资料、源码和运行配置。

官网原则

依据 C4 官网的模型说明整理。

• 用软件系统、容器、组件和代码元素建立分层抽象。
• 用上下文、容器、组件和代码图逐层展开。
• 用系统景观、动态和部署图补充说明。
• 记法独立，可用不同图形表达相同模型。
• 工具独立，可按项目选择绘图工具。

按读者需要选图。多数团队使用上下文图和容器图即可，其余按需补充。选图建议

四个层级

Context

把目标系统作为整体，说明用途、直接使用者和外部协作系统。内部服务、数据库和代码留到后续层级。外部指当前系统边界之外，也包括同公司的其他系统。

Container

展开一个系统，说明应用与数据存储的职责、技术和通信。容器是执行代码或存储数据的运行边界，例如 Web 应用、后台进程和数据库。Docker、虚拟机、目录和依赖库不能直接作为容器划分依据。

Component

展开一个容器，说明具有明确接口的功能单元及其协作。组件在所属容器内执行，通常不独立部署，也不必对应单个目录。

Code

展开一个关键组件，说明相关类、接口、函数或数据结构。只保留解释问题所需的细节，优先从源码或工具生成。Code 是第四层，动态与部署属于补充视图。

视图与参考文件

按需加载视图参考。绘图前读取共用的 绘图与视觉规范。

图	主要问题	模板与检查
L1 系统上下文图	系统怎样与环境协作？	Context
L2 容器图	应用与数据存储怎样通信？	Container
L3 组件图	一个容器内部怎样组织职责？	Component
L4 代码图	一个组件怎样实现？	Code
动态图	一个场景怎样执行？	动态交互
部署图	一个环境中的实例运行在哪里？	部署

系统景观图沿用 Context 的人和系统表示法，范围扩展到多个系统。原生 Mermaid C4 记法见 语法参考。

工作步骤

1. 明确读者、问题、系统边界，以及描述现状还是目标。沿用已确认的范围，标出影响边界的缺口。
2. 查看入口、启动配置、接口、数据访问和部署配置。记录对象的类型、职责、所属对象和来源位置。
3. 选择所需视图，逐层展开关键对象。保留对象身份、外部协作者和关系含义。需要解释行为或环境时补动态或部署图。
4. 交付图、简短解释、依据和待确认项。沿用现有文档位置，未指定时写入 docs/architecture/。

完成检查

• L1 系统、L2 容器、L3 组件和 L4 代码的展开关系一致。未展开的对象留在上层。
• 容器按运行边界划分，组件按内部职责划分。微服务的层级取决于系统边界，团队归属仅作线索。
• 动态交互有结构关系支持，关键状态与异常处理有负责者。超时、重试和幂等策略有依据或待确认标记。
• 部署图注明环境，实例能映射回逻辑容器。副本数、可用区和故障切换有配置依据或明确的设计决定。
• 区分设计目标、源码事实与推断。源码依赖不能单独证明运行调用，示例不作为实际架构的证据。
• 检查 Mermaid 渲染与布局，再核对各视图的语义。记录验证范围，未运行渲染器时注明。

来源与示例约定