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 记法见 语法参考。
工作步骤
- 明确读者、问题、系统边界，以及描述现状还是目标。沿用已确认的范围，标出影响边界的缺口。
- 查看入口、启动配置、接口、数据访问和部署配置。记录对象的类型、职责、所属对象和来源位置。
- 选择所需视图，逐层展开关键对象。保留对象身份、外部协作者和关系含义。需要解释行为或环境时补动态或部署图。
- 交付图、简短解释、依据和待确认项。沿用现有文档位置，未指定时写入
docs/architecture/。
完成检查
- L1 系统、L2 容器、L3 组件和 L4 代码的展开关系一致。未展开的对象留在上层。
- 容器按运行边界划分，组件按内部职责划分。微服务的层级取决于系统边界，团队归属仅作线索。
- 动态交互有结构关系支持，关键状态与异常处理有负责者。超时、重试和幂等策略有依据或待确认标记。
- 部署图注明环境，实例能映射回逻辑容器。副本数、可用区和故障切换有配置依据或明确的设计决定。
- 区分设计目标、源码事实与推断。源码依赖不能单独证明运行调用，示例不作为实际架构的证据。
- 检查 Mermaid 渲染与布局，再核对各视图的语义。记录验证范围，未运行渲染器时注明。