1. 为什么技术方案如此重要？
技术方案不是"写给领导看的形式主义"，而是工程实践中最核心的思维工具。它的本质是——在动手写代码之前，先用最低成本验证你的思路是否正确。
一份好的技术方案能做到：
- 降低返工成本：在文档上改 10 分钟 vs 在代码里改 10 天
- 对齐团队认知：让 reviewer 提前发现你没想到的坑
- 沉淀组织资产：半年后新同学 onboard 时，不需要你口述历史
- 证明你的判断力：方案质量直接反映工程师的技术深度和全局思维
一条黄金法则：如果你的改动涉及 ≥3 个模块、或影响 ≥2 个团队、或上线后 rollback 成本极高——你就必须写技术方案。
2. 技术方案的标准骨架
好的技术方案都遵循相似的结构。以下是经过大量实践验证的 七段式标准骨架，你可以根据项目规模灵活裁剪：
2.1 文档元信息（30 秒让读者定位）
在文档最开头，用一个简洁的表格交代清楚"这是什么、谁写的、现在什么状态"：
| 字段 | 内容 |
|---|---|
| 文档标题 | 清晰、具体，包含关键技术词 |
| 作者 / Owner | 方案的第一责任人 |
| 版本 / 状态 | Draft → In Review → Approved → Archived |
| 最后更新日期 | YYYY-MM-DD 格式 |
| 评审人 | 需要 Sign-off 的关键干系人 |
常见错误：标题太笼统。"XX 系统优化方案" 是坏标题；"XX 系统冷启动耗时从 8s 降至 2s 的技术方案" 是好标题。
2.2 背景与问题（Why：为什么要做这件事）
这一节回答：不做会怎样？做了能怎样？
写作公式：
现状是什么（数据说话）
→ 存在什么问题（量化痛点）
→ 不解决会带来什么后果（业务影响）
→ 我们的目标是什么（可衡量的指标）
示例：
当前首页加载 P99 耗时为 8.2s（数据来源：Grafana 近 7 日），远高于行业标杆的 2s。用户调研显示，加载超 3s 时跳出率上升 40%。按当前日活 500 万计算，每日因慢加载流失约 12 万次访问。本方案目标：将首页加载 P99 降至 ≤2s。
核心原则：
- 用 数据 而非感觉定义问题（"很慢" → "P99 = 8.2s"）
- 用 业务语言 而非纯技术语言描述影响（"缓存未命中" → "每日流失 12 万次访问"）
- 目标必须是 SMART 的（具体、可衡量、可达成、相关、有时限）
2.3 方案设计（What + How：怎么做）
这是整篇方案的核心主体，也是最容易写烂的部分。
分层递进写法：
- 总体架构（Architecture Overview）：先给出一张全局架构图，让读者 30 秒内理解整体设计；标注各模块职责、数据流向、外部依赖
- 核心模块详设（Detailed Design）：每个模块独立一节，包含职责定义、接口设计、关键数据结构、核心算法/流程；用"接口先行"的方式展示模块间的交互契约
- 关键技术决策（Key Decisions）：列出你做过的每一个重要技术选择，用对比表格展示备选方案和最终选择的理由
技术决策对比表模板：
| 维度 | 方案 A：轮询 | 方案 B：WebSocket | 方案 C：SSE |
|---|---|---|---|
| 实时性 | 秒级延迟 | 毫秒级 | 毫秒级 |
| 服务端复杂度 | 低 | 高（需维护连接池） | 中 |
| 客户端兼容性 | 全兼容 | IE 不支持 | 主流浏览器支持 |
| 运维成本 | 低 | 高（长连接资源占用） | 低 |
| 结论 | 不满足实时性要求 | 推荐采用 | 作为备选方案 |
关键原则：不要只展示你选了什么，要展示你为什么没选其他方案。这才是体现技术判断力的地方。
2.4 变更影响范围（Blast Radius）
明确列出将被修改的文件 / 模块 / 服务 / 数据库，以及上下游依赖方：
| 变更对象 | 变更类型 | 影响范围 | 风险等级 |
|---|---|---|---|
| user-service/api/v2/profile.go | 新增接口 | 客户端 SDK 需升级 | 中 |
| order-db.orders 表 | 新增字段 | 需全量回刷 | 高 |
| Kafka topic user-events | 消息格式变更 | 下游 3 个消费者需适配 | 高 |
2.5 风险评估与应对
| 风险 | 概率 | 影响 | 应对措施 |
|---|---|---|---|
| 回刷数据导致 DB 压力激增 | 中 | 线上服务降级 | 分批回刷 + 限流 + 低峰期执行 |
| WebSocket 大量断连重连 | 低 | 用户体验劣化 | 客户端指数退避重连 + 降级为轮询 |
| 新旧接口并行期数据不一致 | 高 | 业务数据错误 | 双写 + 对账脚本 + 灰度验证 |
2.6 上线计划（Rollout Plan）
- 灰度策略：1% → 10% → 50% → 全量，每阶段观察核心指标 ≥24h
- 监控看板：列出关键告警规则和 Grafana 面板链接
- 回滚方案：一键回滚的具体操作步骤（不是"回滚代码"这种废话）
- 时间线：甘特图或里程碑表，标注关键节点和 Owner
2.7 验证标准（Definition of Done）
| 验证维度 | 具体标准 | 验证方式 |
|---|---|---|
| 功能正确性 | 全部 API 通过集成测试 | CI 自动化 |
| 性能达标 | P99 ≤ 2s | 压测报告 |
| 数据一致性 | 新旧系统数据对账 0 diff | 对账脚本 |
| 灰度稳定 | 全量后 72h 内无 P0 告警 | 监控看板 |
3. 写作心法：从"能看懂"到"想看完"
3.1 金字塔原则：先说结论，再说为什么
错误写法：
我们调研了 Redis、Memcached 和本地缓存三种方案。Redis 支持丰富的数据结构但运维成本高...Memcached 简单但不支持持久化...本地缓存无网络开销但有一致性问题...综合考虑，我们选择 Redis。
正确写法：
推荐方案：Redis。 理由：(1) 支持 Hash 结构，天然适配用户 Profile 场景；(2) 集群模式已有运维经验；(3) 持久化能力保障冷启动不丢缓存。以下是与其他方案的详细对比...
3.2 三层读者法则
一份好方案应该同时服务三类读者：
| 读者类型 | 他们关心什么 | 如何服务 |
|---|---|---|
| 扫读者（TL/PM，2 分钟） | 做什么、为什么、什么时候上线 | 摘要 + 背景 + 时间线 |
| 审阅者（架构师，15 分钟） | 方案是否合理、有无遗漏 | 架构图 + 决策对比表 + 风险评估 |
| 实施者（开发者，反复查阅） | 具体怎么改、改哪些文件 | 详细设计 + 接口定义 + 变更列表 |
3.3 段落的黄金节奏
- 一个段落只说一件事，段落间用空行分隔
- 长段落 ≤ 5 行。超过 5 行的段落，读者的注意力会断裂
- 交替使用：段落文字 → 表格 → 代码块 → 图 → 段落文字，节奏变化让阅读体验更好
- 善用加粗：每个段落的核心论点加粗，帮助扫读者快速抓取信息
3.4 避免的写作陷阱
| 陷阱 | 示例 | 修正 |
|---|---|---|
| 大段无结构文字 | 连续 3 段纯文字描述架构 | 先放架构图，再用文字解释 |
| 只写"是什么"不写"为什么" | "我们用 Redis 做缓存" | "我们用 Redis 做缓存，因为..." |
| 过度细节 | 方案里贴了 200 行代码 | 只贴核心 10 行 + 完整代码链接 |
| 缺少量化 | "性能有明显提升" | "P99 从 8.2s 降至 1.8s" |
| 自嗨式叙事 | "经过我深入的调研和分析" | 直接给结论和依据 |
4. 图表使用指南：一图胜千言
4.1 选图决策树
遇到任何需要画图的场景，先问自己一个问题：我想表达什么类型的关系？
| 我想表达... | 应该用... | 典型工具 |
|---|---|---|
| 系统由哪些模块组成、模块间如何交互 | 架构图 | Mermaid flowchart |
| 一个请求/流程从头到尾经过哪些步骤 | 流程图 | Mermaid flowchart |
| 多个角色/系统之间的调用时序 | 时序图 | Mermaid sequenceDiagram |
| 系统在不同条件下的状态切换 | 状态机图 | Mermaid stateDiagram |
| 数据库表之间的关系 | ER 图 | Mermaid erDiagram |
| 概念的层级分解 | 思维导图 | Mermaid mindmap |
| 项目的时间安排 | 甘特图 | Mermaid gantt |
| 不同方案的优劣对比 | 对比表格 | Markdown table |
| 数据分布或占比 | 饼图 | Mermaid pie |
4.2 六种必学图表的画法与场景
图表一：架构图（最常用，几乎每篇方案必备）
适用场景：展示系统全貌——有哪些模块、模块间怎么交互、数据怎么流转。
画法要点：
- 分层/分区：用 subgraph 将模块按层级或职责分组
- 数据流向：箭头代表调用关系或数据流向，标注协议/格式
- 外部依赖：用不同样式区分内部模块与外部服务
Mermaid 示例：
黄金法则：
- 一张架构图不超过 15 个节点。超过了就拆分为"全局总览图 + 模块详情图"
- 箭头上标注 协议/格式（HTTP/gRPC/Kafka），让读者一眼看清交互方式
- 从上到下（TB）或从左到右（LR）布局，不要混用方向
图表二：时序图（展示调用链的最佳选择）
适用场景：多个系统/模块之间的调用时序、请求-响应流程。
画法要点：
- 参与者从左到右按调用顺序排列
- 用 activate/deactivate 表示处理耗时
- 用 alt/opt/loop 表示条件/可选/循环逻辑
- 标注关键的请求参数和返回值
Mermaid 示例：
黄金法则：
- 一张时序图不超过 7 个参与者、15 次交互
- 异步调用用虚线箭头区分同步调用
- 重点标注 错误/超时/降级 的分支路径
图表三：流程图（决策逻辑和步骤的首选）
适用场景：算法步骤、业务流程、审批流程、异常处理。
Mermaid 示例：
黄金法则：正常流程从上到下一条直线，异常分支向两侧展开；每个判断节点最多 2~3 个出口；超过 10 个步骤时，考虑拆分为子流程。
图表四：状态机图（状态流转的最佳表达）
适用场景：订单状态流转、任务生命周期、连接状态管理。
Mermaid 示例：
黄金法则：标注每条转换的触发条件；标注终态；状态数量控制在 10 个以内。
图表五：ER 图（数据库设计必备）
适用场景：展示数据库表之间的关联关系。
Mermaid 示例：
图表六：思维导图（概念分解和头脑风暴）
适用场景：方案初期的思路发散、复杂概念的层级分解。
Mermaid 示例：
4.3 画图的十条铁律
| 序号 | 铁律 | 说明 |
|---|---|---|
| 1 | 先画再写 | 画图是最好的思维工具。先画图理清思路，再用文字补充细节 |
| 2 | 一图一主题 | 一张图只传达一个核心信息。别把架构图、时序图、部署图塞进一张图里 |
| 3 | 节点不超15 | 超过 15 个节点的图，读者的认知负荷会急剧上升。必须拆分 |
| 4 | 有图必有文 | 图下面必须跟 2~3 句文字解释这张图的要点。图是辅助，不是替代 |
| 5 | 箭头有含义 | 每条箭头都要标注含义：调用协议、数据格式、触发条件 |
| 6 | 统一方向 | 一张图里的信息流只往一个主方向走（从上到下或从左到右） |
| 7 | 颜色有节制 | 最多用 3 种颜色区分元素类别。颜色过多等于没有颜色 |
| 8 | 避免交叉线 | 如果线条大量交叉，说明你的布局需要调整，或者图需要拆分 |
| 9 | 用代码画图 | 优先使用 Mermaid/PlantUML 等代码即图表的方式，方便版本管理和协作 |
| 10 | 迭代优化 | 第一版图一定是丑的。画完后问自己：一个不了解背景的人能看懂吗？ |
4.4 图文配合的编排节奏
一篇好的技术方案，图和文的配合应该像呼吸一样自然：
节奏法则：每隔 300~500 字，就应该出现一个可视化元素（图、表、代码块）打断纯文字的单调节奏。
5. Mermaid 语法速查表
在飞书文档中，Mermaid 是最便捷的画图方式。以下是最常用的语法速查：
5.1 图表声明语法
| 图表类型 | 声明语法 | 适用场景 |
|---|---|---|
| 流程图/架构图 | flowchart TD 或 flowchart LR | 模块关系、流程步骤 |
| 时序图 | sequenceDiagram | 多系统调用时序 |
| 状态机图 | stateDiagram-v2 | 状态流转 |
| ER 图 | erDiagram | 数据库表关系 |
| 甘特图 | gantt | 项目排期 |
| 思维导图 | mindmap | 概念分解 |
| 饼图 | pie | 数据占比 |
| 类图 | classDiagram | 面向对象设计 |
5.2 常用节点与箭头
节点形状：[矩形] 用于普通操作/服务，(圆角矩形) 用于开始/结束，{菱形} 用于判断/条件，[(圆柱体)] 用于数据库，((圆形)) 用于连接点/根节点。
箭头样式：--> 实线箭头（同步调用），-.-> 虚线箭头（异步/可选），==> 粗线箭头（重点强调），-- 文字 --> 带标注的箭头。
6. 自检清单：发出 Review 前的最后一关
结构完整性
- 有文档元信息（标题、作者、状态、日期）
- 有背景与问题描述，且用数据量化了痛点
- 有明确的、可衡量的设计目标
- 有总体架构图 + 至少一张全局视角的可视化
- 有核心技术决策的对比分析（而非只写结论）
- 有变更影响范围清单（Blast Radius）
- 有风险评估与应对措施
- 有上线计划（灰度策略 + 回滚方案）
- 有验证标准（怎么证明做完了）
表达质量
- 标题具体且包含关键信息（不是"XX 优化"）
- 每个段落不超过 5 行
- 每隔 300~500 字有一个可视化元素（图/表/代码块）
- 关键结论已加粗
- 所有数据都标注了来源
- 没有"可能"、"大概"、"应该还行"等模糊表述
图表质量
- 每张图只传达一个核心信息
- 节点数量不超过 15
- 箭头都标注了含义
- 图下方有文字解释
- 信息流方向统一
7. 不同规模方案的裁剪指南
不是所有改动都需要写一份 10 页的方案。根据改动的规模和风险，灵活裁剪：
| 规模 | 判断标准 | 建议内容 | 预计篇幅 |
|---|---|---|---|
| S 号 | 3 个文件以内，无跨团队依赖 | 背景 + 方案简述 + 变更列表 | 1 页 |
| M 号 | 3 | 完整七段式，图表可精简 | 3~5 页 |
| L 号 | 10 个文件以上，跨多团队，涉及数据迁移 | 完整七段式 + 详细设计子文档 | 5~15 页 |
| XL 号 | 新建系统，影响全链路 | 完整七段式 + 每模块独立子方案 | 15 页以上，拆分为系列文档 |
核心原则：方案的长度不是目的，降低风险、对齐认知 才是目的。能用 1 页说清楚的事，不要写 10 页。
