架构案例模板

要点

  • 架构案例记录模块划分、依赖关系、扩展性决策
  • 重点写清楚：为什么这样拆分模块、依赖怎么管理、未来怎么扩展
  • 架构图比文字描述更有效——先给图，再解释关键决策
  • 架构决策通常有长期影响——写清楚回退成本和演进路径

1. 适用场景

架构案例用于记录系统的模块划分、服务边界、数据流、依赖管理等结构性决策。

典型场景：

  • 从单体拆分为微服务
  • 引入新的中间件（消息队列、缓存、搜索引擎）
  • 设计多租户隔离方案
  • 选择前后端分离或全栈框架

2. 模板结构

# [架构决策标题]
 
## 背景
 
什么系统、什么业务场景、为什么要做这个架构决策。
 
## 约束
 
- 团队规模和技能
- 时间窗口
- 兼容性要求
- 性能/容量需求
 
## 架构图
 
用图展示模块划分、服务边界、数据流。
 
## 关键决策
 
### 决策 1：[标题]
 
选择了什么、放弃了什么、取舍理由。
 
### 决策 2：[标题]
 
...
 
## 依赖管理
 
外部依赖、内部依赖、版本策略。
 
## 扩展性
 
未来可能怎么演进、当前的扩展点在哪。
 
## 结果
 
上线后的实际效果、指标变化。
 
## 复盘
 
- 哪些决策是对的
- 哪些决策需要调整
- 后续行动项

3. 写作要点

架构图先行

架构案例必须有图。文字描述模块关系很抽象，图一目了然。

图可以是：

  • 模块依赖图
  • 服务调用时序图
  • 数据流图
  • 部署架构图

重点写拆分决策

架构案例的核心是「为什么这样拆分」。写清楚：

  • 拆分的边界在哪里
  • 为什么这个边界而不是那个边界
  • 拆分后的通信方式（同步/异步、HTTP/消息队列）
  • 数据怎么流转

承认技术债

架构决策通常有取舍。写清楚：

  • 当前方案的局限
  • 引入的技术债
  • 未来还债的成本

4. 示例

# 订单系统从单体拆分为订单服务和支付服务
 
## 背景
 
订单系统日均 50 万单，单体应用代码量超过 20 万行。订单和支付耦合在一起，
修改支付逻辑需要回归测试整个订单流程，迭代速度慢。
 
## 约束
 
- 3 个后端工程师，不能停其他需求
- 订单 API 不能变，上游系统不配合改造
- 订单和支付的数据一致性必须保证
 
## 架构图
 
[图：订单服务 → 消息队列 → 支付服务]
 
## 关键决策
 
### 决策 1：按业务领域拆分，不按数据表拆分
 
选择了按业务领域（订单、支付）拆分，而不是按数据表拆分（订单表、支付表）。
 
理由：按数据表拆分只是物理拆分，业务逻辑还是耦合。按领域拆分后，
订单服务和支付服务可以独立迭代。
 
### 决策 2：异步通信，最终一致性
 
订单创建后，发消息到队列，支付服务异步处理。放弃分布式事务。
 
理由：分布式事务性能差，团队没有经验。最终一致性可以接受，因为支付结果
本来就是异步通知的。
 
## 依赖管理
 
- 订单服务依赖支付服务的回调接口（同步）
- 支付服务依赖订单服务的订单查询接口（同步）
- 双方通过消息队列解耦核心流程
 
## 扩展性
 
- 支付服务可以独立扩容
- 未来可以引入风控服务，作为独立的消费者
 
## 结果
 
- 订单和支付可以独立发布，迭代速度提升 50%
- 支付相关的 bug 减少 30%（影响范围缩小）
 
## 复盘
 
- 拆分是正确的，但低估了数据一致性校验的工作量
- 消息队列的监控和告警需要加强
- 后续行动：引入对账系统，每天校验订单和支付的一致性

总结

架构案例的核心是模块划分和依赖管理。必须有架构图，重点写拆分决策和取舍，承认技术债和局限。