技术方案设计与评审

设计文档是「在动手前用最低成本犯错」的工具。本文给出一份中型需求的方案模板，以及评审时真正该盯的几个点。

一、什么时候必须写方案

判断标准很简单：如果做错了需要回滚数据或重构，就值得先写一页纸。

二、方案模板

# XX 技术方案
## 1. 背景与约束
   目标、时间/人力约束、必须兼容的既有行为
## 2. 现状与问题
   现有链路（图）、瓶颈、历史包袱
## 3. 方案选型
   至少 2~3 个候选，逐项对比，说明取舍理由与放弃原因
## 4. 详细设计
   架构图 / 时序图、模块划分、接口契约、数据表 DDL
   关键算法、状态机、并发与幂等处理
## 5. 非功能设计
   性能容量估算、监控告警、安全与权限、日志埋点
## 6. 兼容与迁移
   灰度策略、数据迁移步骤、双写/回滚窗口、旧版本兼容
## 7. 风险与兜底
   逐条列出风险 + 触发条件 + 应对动作
## 8. 排期与验证
   拆分任务、里程碑、验收方式

「候选方案对比」是最容易被跳过、也最能体现设计质量的一节。只写一个方案，评审就退化成点头会。

三、选型对比表怎么写

结论写法示例：本期选 B，因为峰值流量是主要矛盾且业务允许秒级延迟；代价是引入补偿任务，已在第 4 节给出幂等设计。

四、四个必须画清楚的图

1. 架构图：新增组件放在哪一层，与谁通信，走内网还是公网。
2. 时序图：一次请求跨了哪些服务、每步失败会怎样。
3. 状态机图：核心实体的状态流转，标出不可达与非法跳转。
4. 数据迁移图：老数据 → 新数据的路径、双写期、校验方式、回滚点。

图不必精美，但必须能被别人复述出来。Mermaid 很适合放进 md，评审时改起来也快：

sequenceDiagram
    participant C as 客户端
    participant A as 订单服务
    participant Q as 消息队列
    participant B as 通知服务
    C->>A: 提交订单
    A->>A: 事务内写订单
    A->>Q: 投递订单创建事件
    A-->>C: 返回成功
    Q->>B: 消费事件
    B->>B: 发送通知（幂等）

五、评审时真正该盯的六件事

不要在设计评审里纠结命名和缩进，那是代码评审的事。

六、常见坑与对策

• 方案写成代码清单：把大段实现贴进文档，读者抓不住决策点 → 只保留契约与决策。
• 只考虑成功路径：所有「异常」章节留空 → 强制填写失败路径表。
• 容量靠感觉：「应该扛得住」 → 给出 QPS、数据量、存储增长的粗算过程。
• 没有灰度：全量一把梭 → 明确开关、灰度维度（用户 / 比例 / 租户）、观察指标。
• 评审无结论：会开完没人拍板 → 记录「通过 / 有条件通过 / 驳回」+ 待办 + 责任人。

七、小结

好方案的两个特征：别人能看懂你为什么这么选，以及别人能提前看到失败时会发生什么。如果一份设计文档里没有「放弃其他方案的理由」和「回滚步骤」，它大概率还没写完。