第 14 章 · C4 模型与架构工件交付包
本章提供 可直接用于 ARB 评审与 L3 认证 的架构工件标准：C4 图、时序图、ADR、接口契约、容量工作表与交付目录规范。原独立 deliverables/ 目录已移除，全部模板内嵌本章，跟练章节 ch16～ch18 直接引用。
前置：ch01 分层与 NFR；ch13 ARB 流程与材料清单。
交叉引用：ch09 容量工作表；ch13 SLO 面板；ch16/ch17/ch18 跟练提交物。
14.1 为什么用 C4，而不是「一张大图」
| 问题 | 单张大图 | C4 分层 |
|---|---|---|
| 受众混杂 | 老板看不懂细节 | Context 给全员，Container 给工程师 |
| 维护成本 | 改一处牵全身 | 按层级独立更新 |
| 评审效率 | 20 分钟讲不清边界 | 先 Context 2 分钟，再 Container 5 分钟 |
C4 四层模型
| 层级 | 英文 | 受众 | 内容粒度 | 评审是否必须 |
|---|---|---|---|---|
| 1 | Context | 产品、管理层、新人 | 系统与外部角色/系统 | ✅ 必须 |
| 2 | Container | 开发、运维、架构 | 应用、DB、MQ、部署单元 | ✅ 必须 |
| 3 | Component | 开发 | 服务内部模块 | 详细设计阶段 |
| 4 | Code | 开发 | 类/包（IDE 生成） | 可选 |
命名注意：C4 的 Container = 部署容器（进程/应用），≠ Docker 容器。贤紫课程中 Deployment/Pod 映射到 C4 Container。
14.2 Context 图（贤紫社区电商）
目的：回答「系统与谁交互、解决什么业务问题」。
flowchart LR
subgraph 用户侧
C[消费者]
M[商家]
CS[客服]
end
subgraph 贤紫社区电商
SHOP[社区电商系统]
end
subgraph 外部系统
PAY[微信支付/支付宝]
SMS[短信网关]
LOG[物流开放平台]
AI[小紫 AI 客服]
end
C -->|浏览/下单| SHOP
M -->|上架/发货| SHOP
CS -->|工单/退款| SHOP
SHOP -->|支付请求| PAY
PAY -->|回调| SHOP
SHOP -->|验证码| SMS
SHOP -->|运单查询| LOG
SHOP -->|智能问答| AIContext 图标注规范
| 元素 | 写法 |
|---|---|
| 系统边界 | 虚线框 + 系统名 |
| 关系 | 动词短语：下单、支付回调 |
| 技术细节 | 不写（留给 Container） |
| 导出 | Mermaid Live / draw.io → PNG/SVG |
14.3 Container 图（生产拓扑）
目的：回答「有哪些可部署单元、用什么技术、如何通信」。
flowchart TB
subgraph 接入层
GW[APISIX Ingress<br/>TLS 终止]
end
subgraph 应用层 prod-app
BFF[web-bff]
CAT[catalog-api<br/>Django]
ORD[order-api<br/>Django]
USR[user-api<br/>Django]
PAY[payment-worker]
end
subgraph 数据层 prod-middleware
MY[(MySQL 8<br/>主从)]
RD[(Redis 7<br/>集群)]
KF[Kafka 3 Broker]
ES[(Elasticsearch)]
MO[MinIO]
end
subgraph 可观测
PR[Prometheus]
GF[Grafana]
LO[Loki]
end
C[用户] --> GW
GW --> BFF & CAT & ORD & USR
BFF --> CAT & ORD
ORD --> MY & RD & KF
CAT --> MY & MO & ES
USR --> MY & RD
KF --> PAY
PAY --> MY
ORD -.-> PR
GW -.-> PR
PR --> GFContainer 图必备标注
| 标注项 | 示例 |
|---|---|
| Namespace | prod-app、prod-middleware |
| 副本数 | order-api ×6（大促，见 ch16） |
| 协议 | HTTPS、gRPC、TCP 3306 |
| 数据流向 | 实线同步，虚线异步/监控 |
与 ch12/ch18 交叉：双活时在 Container 图注明 cluster-a / cluster-b 各副本数与 GSLB 权重。
14.4 Component 图（order-api 内部，选学）
flowchart LR
subgraph order-api
CTRL[OrderController]
SVC[OrderService]
INV[InventoryClient]
PAY[PaymentPublisher]
CACHE[StockCache]
end
CTRL --> SVC
SVC --> INV & PAY & CACHE
INV -->|HTTP| CAT
CACHE -->|TCP| RD[(Redis)]
SVC -->|SQL| MY[(MySQL)]
PAY -->|Produce| KF[Kafka]Component 级评审关注：缓存击穿点（ch17 StockCache）、事务边界、幂等键。
14.5 时序图：下单链路（Tier-0）
sequenceDiagram
autonumber
participant U as 用户
participant G as APISIX
participant O as order-api
participant R as Redis
participant M as MySQL
participant K as Kafka
participant P as payment-worker
U->>G: POST /api/v1/orders
G->>G: JWT 校验 + 限流
G->>O: 转发（traceId）
O->>R: GET stock:{skuId}
alt 缓存命中
R-->>O: qty
else 缓存未命中
O->>M: SELECT qty FROM inventory
M-->>O: qty
O->>R: SETEX + TTL 抖动
end
O->>M: BEGIN; INSERT order; UPDATE inventory
O->>K: OrderCreated
O-->>G: 201 {orderId}
G-->>U: 201
K->>P: consume
P->>M: 更新支付状态时序图评审检查点
| 步骤 | 风险 | 关联章节 |
|---|---|---|
| Redis GET | 击穿 | ch17 |
| MySQL 事务 | 死锁、慢查询 | ch10 |
| Kafka 发送 | 重复消费 | ch05 |
| 限流 | 大促保护 | ch16 |
14.6 ADR 完整模板（Architecture Decision Record）
以下模板为 L3 认证与 ch16/ch17/ch18 跟练 的统一格式。每份 ADR 一个文件，编号连续。
# ADR-{编号} {简短标题}
| 元数据 | 值 |
|--------|-----|
| 状态 | 提议中 / 已采纳 / 已废弃 / 已取代 |
| 日期 | 2026-08-18 |
| 决策者 | 张三（架构）、李四（SRE） |
| 关联评审 | ARB-2026-0818-001 |
| 取代 | ADR-000（如有） |
## 背景（Context）
描述业务与技术背景：要解决什么问题？约束是什么？
- 业务：双 11 下单峰值预计 150 QPS（见 ch16 §16.2）
- 技术：当前 3 副本，k6 实测 QPS>170 时 P99 超标
- 约束：RTO < 15min（ch18）、错误预算政策（ch13）
## 决策（Decision）
我们决定：**将 order-api 常态副本从 3 扩至 6，HPA maxReplicas=10**。
## 备选方案（Options Considered）
### 方案 A：垂直扩容（单 Pod 8C16G）
- 优点：改动小
- 缺点：单点风险、HPA 无效、成本不一定更低
- 结论：**拒绝**
### 方案 B：水平扩容至 6 副本 + HPA
- 优点：符合无状态设计（ch03）、可回缩
- 缺点：+3 Pod 成本（ch09 §9.5）
- 结论：**采纳**
### 方案 C：拆分为 order-write / order-read 微服务
- 优点：读写分离彻底
- 缺点：工期 6 周+，大促前来不及
- 结论：**延期至 Q1**
## 后果（Consequences）
### 正面
- P99 在大促毛刺下维持 <400ms
- 符合 ch13 SLO 99.95%
### 负面 / 风险
- 月成本 +0.45 单位（ch09）
- MySQL 连接数增加：6×20=120，需确认 max_connections
- 需更新 C4 Container 图副本标注
## 验证计划（Validation）
- [ ] staging k6：80 VU 稳态 P99 <400ms，错误率 <0.1%
- [ ] Grafana 截图归档
- [ ] 大促后缩容至 3 副本（Runbook 步骤 8）
## 合规与安全（如适用）
- 不涉及新增个人数据处理（ch15）
- 无新的外网暴露面
## 参考
- ch09 容量公式、ch13 ARB 流程、ch16 跟练任务二