案例沉淀方法

要点

案例沉淀不是写文档——是把团队踩过的坑、做过的决策、观察到的规律固化成可复用的知识
好的案例回答五个问题：背景是什么、约束有哪些、做了什么决策、结果怎么样、学到了什么
案例的价值在于可判断——读者看完能知道「这个做法适不适合我的场景」
模板不是填空题——每个部分都有明确的写作目的，避免凑字数
定期复审比一次性写完更重要——假设会变，上下文会变，案例也会过期

1. 为什么要沉淀案例

工程团队最常犯的两个错误：

重复踩坑——同一个问题，不同团队、不同时间遇到，各自摸索解决方案
知识流失——核心成员离职后，关键决策的背景和约束没人记得

案例沉淀解决这两个问题。把决策过程写下来，新人可以看「为什么当初这样做」；把失败经验写下来，后人可以避免重蹈覆辙。

但案例沉淀也有成本：

写案例需要时间——工程师通常不愿意写
案例会过期——技术栈变了、业务变了，案例的前提可能不成立
案例可能被误用——脱离上下文照搬做法，反而引入问题

所以案例沉淀的核心原则：写有用的，不写所有的。

2. 什么样的案例值得写

不是所有工作都值得写案例。值得沉淀的案例通常满足以下条件之一：

决策有争议

团队内部对方案有分歧，最后选择了 A 而不是 B。写下来：为什么选 A、放弃了什么、有什么风险。后续有人问「为什么不选 B」时，直接指向案例。

踩过坑

系统出过故障、性能突然下降、迁移中途卡住。写下来：问题怎么发现的、根因是什么、怎么修复的、怎么防止再发生。

有复用价值

解决了一个通用问题——比如怎么在 Workers 里做文件分片上传、怎么设计多租户隔离。写下来：适用场景、实现要点、边界条件。其他团队遇到类似问题时可以参考。

违反直觉

实际结果和预期不符——以为会快的方案反而慢、以为安全的做法其实有漏洞。写下来：预期是什么、实际是什么、为什么会有差异。这类案例最有教学价值。

3. 案例的核心结构

每个案例都应该回答五个问题。不是每个问题都需要很长的篇幅，但不能缺失。

背景

系统是什么、业务是什么、触发这次工作的原因是什么。

读者需要知道：这个案例和我的场景有多接近。如果背景差太远，案例的结论可能不适用。

## 背景
 
我们的订单系统跑在单体应用上，日均订单量 10 万。2024 年 Q3 开始，订单量增长到日均 50 万，
数据库写入成为瓶颈。团队决定拆分订单服务，把写入链路独立出来。

约束

时间、人力、兼容性、风险——决策不是在真空里做的。

读者需要知道：为什么没有选「更好的方案」。很多时候「更好的方案」在当前约束下不可行。

## 约束
 
- 时间：Q4 必须完成，否则大促扛不住
- 人力：只有 3 个后端工程师，不能停其他需求
- 兼容性：上游系统不能改，必须保持 API 不变
- 风险：订单不能丢，不能有超过 5 分钟的停机

决策

选了什么方案、放弃了什么方案、取舍理由是什么。

这是案例的核心。不是写「我们做了什么」，而是写「为什么这样做而不是那样做」。

## 决策
 
采用「异步写入 + 最终一致性」方案：
 
1. 订单 API 接收请求后，写入消息队列，立即返回「已接收」
2. 订单消费者从队列读取，写入数据库，更新状态
3. 查询 API 同时查主库和队列，返回最新状态
 
放弃的方案：
 
- 垂直拆分数据库：需要改上游系统，时间不够
- 读写分离：写入瓶颈没解决，只是推迟问题
 
取舍：引入最终一致性，用户下单后需要 1-2 秒才能查到订单。
业务接受这个延迟，因为订单确认邮件也是异步发送的。

结果

上线后怎么样——指标变化、用户影响、残留问题。

没有结果的案例是半成品。读者需要知道：这个方案到底行不行。

## 结果
 
2024 年 9 月上线，大促期间（11 月）日均订单量达到 80 万：
 
- 订单 API P99 延迟从 800ms 降到 120ms
- 数据库写入 QPS 从 500 提升到 3000
- 没有出现订单丢失或重复
 
残留问题：
 
- 队列积压时，订单状态更新延迟会增加到 5-10 秒
- 消费者偶尔崩溃，需要人工重启（已加监控告警）

复盘

学到了什么——可复用的原则、后续行动项。

案例的最后要提炼出可迁移的知识。不是「我们做得很好」，而是「下次遇到类似场景，可以怎么想」。

## 复盘
 
1. 异步化是解决写入瓶颈的有效手段，但要接受最终一致性
2. 队列选型要看团队熟悉度，RabbitMQ 和 Kafka 都能解决问题
3. 监控要先于上线——消费者崩溃的问题在压测时没发现，上线后才暴露
4. 后续行动：把消费者改成无状态，支持自动扩缩容

4. 写作原则

先讲场景和约束，再讲方案

不要上来就写「我们用了 Kafka」。先讲为什么选 Kafka 而不是 RabbitMQ——是因为团队熟悉、还是因为吞吐需求、还是因为已有基础设施。

把判断绑定到证据

「这个方案性能很好」不是判断，是观点。要有证据：

P99 延迟从 800ms 降到 120ms
QPS 从 500 提升到 3000
内存占用减少 40%

没有证据的判断，读者无法验证，也无法判断是否适用于自己的场景。

承认取舍和局限

没有完美的方案。每个选择都有代价——写清楚代价，读者才能判断是否值得。

「这个方案引入了最终一致性，用户下单后需要 1-2 秒才能查到订单」比「这个方案很好」更有价值。

保持可判断性

案例的结论应该是可判断的——读者看完能知道「这个做法适不适合我的场景」。

「我们在订单系统里用了事件驱动架构」不是结论，是描述。「事件驱动适合写入密集、读延迟可接受的场景，不适合强一致性要求高的场景」才是结论。

5. 案例模板

不同类型的案例有不同的侧重点：

类型	侧重点
架构案例	模块划分、依赖关系、扩展性
事故案例	根因分析、时间线、修复措施、预防手段
性能案例	瓶颈定位、优化手段、指标对比
迁移案例	迁移策略、风险控制、回滚方案
重构案例	重构动机、渐进策略、测试覆盖
AI 工程案例	模型选型、Prompt 设计、评估指标

后续文章提供每类案例的具体模板。模板不是填空题——每个部分都有明确的写作目的，避免凑字数。

6. 案例的生命周期

案例不是写完就结束。它有生命周期：

创建

触发条件：决策有争议、踩了坑、有复用价值、违反直觉。

写作者：亲历者。不是旁观者代写——亲历者记得约束和取舍，旁观者只记得结果。

复审

触发条件：

技术栈升级——案例里提到的工具版本已经过时
业务变化——案例的前提条件不再成立
新发现——上线后发现了案例没提到的问题

复审者：新的使用者。他们能从读者视角发现案例的盲点。

7. 常见误区

只写成功，不写失败

成功案例当然有价值，但失败案例的教学价值更高。写清楚：预期是什么、实际是什么、为什么有差异、学到了什么。

只写方案，不写约束

「我们用了微服务架构」不是案例，是简历。要写：为什么选微服务而不是单体、团队规模是否支持、运维成本是否接受。

只写结论，不写过程

「性能优化后延迟降低 80%」是结果，不是案例。要写：瓶颈在哪、怎么定位的、尝试了哪些方案、为什么选这个方案。

案例太长

案例不是论文。背景 1-2 段，约束 3-5 条，决策重点写取舍，结果用指标说话，复盘提炼 3-5 条原则。总计 1000-2000 字足够。

总结

回顾这篇的要点：

案例沉淀解决两个问题：重复踩坑、知识流失
值得写的案例：决策有争议、踩过坑、有复用价值、违反直觉
案例的核心结构：背景、约束、决策、结果、复盘
写作原则：先讲场景和约束、把判断绑定到证据、承认取舍和局限、保持可判断性
不同类型的案例有不同的侧重点——架构、事故、性能、迁移、重构、AI 工程各有模板
案例有生命周期：创建、复审、归档
常见误区：只写成功不写失败、只写方案不写约束、只写结论不写过程、案例太长

后续文章提供每类案例的具体模板和写作指导。