1. 这不是笔记是系统设计能力的“肌肉记忆”训练手册“system-design-notes”这个标题乍看平平无奇像极了某位工程师随手建的 GitHub 仓库名或是某次面试前熬夜整理的 Notion 页面。但如果你真把它当成普通笔记来抄、来背、来收藏吃灰那它就真的只是个空壳——而你大概率会在下一次系统设计面试里卡在“如何支撑千万级用户同时下单”这个问题上支吾半天最后只挤出一句“加缓存…上消息队列…”。这不是知识储备的问题是思维结构没长出来。我带过三十多个刚转岗后端或准备跳槽的工程师90% 的人栽在同一个地方他们能默写出 CAP 定理的定义却说不清为什么在电商秒杀场景里要主动放弃 C一致性而不是 P分区容错性或 A可用性他们知道微服务拆分有“高内聚、低耦合”原则但一到画边界就把订单、支付、库存全塞进一个“交易服务”里美其名曰“方便调用”。这背后缺的不是知识点是把抽象原则翻译成具体决策的“翻译器”。而 system-design-notes本质上就是这个翻译器的训练日志——它不记录结论它记录推演过程不堆砌术语它暴露思考断层不追求完整它刻意保留“当时没想到这里”的空白。我自己的 notes 仓库里至今还留着三年前第一次画分布式事务流程图时在“本地消息表”和“Saga 模式”之间划了三道叉旁边手写批注“这里漏了补偿失败的重试兜底重试次数怎么定超时怎么设谁来监控失败”——正是这些带着毛边的、不完美的记录成了后来带新人时最管用的教学素材。它适合谁适合所有已经写过 CRUD、能跑通 Spring Boot 单体应用但一听到“日均 PV 百万”“峰值 QPS 5000”“数据量从 GB 级涨到 PB 级”就开始心慌的人。它不教你怎么写代码它教你先想清楚这个系统到底要“扛住什么”又“不能失去什么”。2. 内容整体设计与思路拆解为什么笔记必须“反完美主义”2.1 核心设计逻辑从“知识容器”转向“思维脚手架”绝大多数人整理 system-design notes 的第一反应是建一个目录树/01-基础理论 /02-数据库 /03-缓存 /04-消息队列 /05-微服务…然后往里填教科书式的定义、优缺点对比、选型表格。这看似条理清晰实则埋下巨大隐患。我见过太多人笔记记得密密麻麻面试时被问“如果 Redis 集群脑裂了你的订单服务会怎样”对方愣住翻笔记翻到“Redis Cluster 架构”一页上面写着“采用 Gossip 协议同步状态”但下面没有一行字解释“Gossip 同步延迟如何影响主从切换判断”更没有模拟过“网络分区发生时客户端请求打到旧主节点写入成功但未同步分区恢复后数据丢失”的完整链路。问题出在哪出在笔记的设计目标错了——它被当成了“知识容器”目标是“装得全”而真正有效的 system-design notes必须是“思维脚手架”目标是“搭得稳”。脚手架的核心功能是什么是支撑你站在上面看清脚下每一块木板组件的承重极限、连接松动点、以及风流量/故障吹来时哪里最先晃。所以我的 notes 仓库结构完全反常规没有按技术栈分类而是按“设计决策流”组织。顶层只有四个目录/decisions关键决策记录、/tradeoffs权衡分析、/failure-modes故障模式推演、/scale-benchmarks规模基准测试。比如/decisions/2023-08-order-id-generation.md内容不是罗列 Snowflake、UUID、数据库自增而是记录一次真实选型过程“业务需求全局唯一、趋势递增利于 MySQL BTree 索引、64 位整数、支持 10 万 QPS。排除 UUID字符串存储开销大索引效率低排除 DB 自增单点瓶颈无法水平扩展Snowflake 候选但需解决时钟回拨风险。最终方案改造 Snowflake引入‘逻辑时钟’替代物理时间戳配合 ZooKeeper 分配 Worker ID。验证压测 12 万 QPSID 生成延迟 P99 2ms时钟回拨模拟下无重复。”——你看它不告诉你 Snowflake 是什么它逼你回答“为什么是它而不是别的”。2.2 方案选型背后的硬逻辑成本、可控性、演化性三角为什么不用 Kafka 而用 RocketMQ为什么数据库分库分表选 ShardingSphere 而非 MyCat为什么缓存穿透要用布隆过滤器而非简单空值缓存这些选择背后绝非“听说它快”或“公司主流用它”这么简单。我的 notes 里每个技术选型都强制绑定三个维度的成本核算显性成本服务器资源CPU/内存/磁盘 IO、带宽消耗、商业许可费用。例如评估 Redis Cluster vs CodisRedis Cluster 原生支持但集群管理复杂度高运维人力成本隐性上升Codis 提供 Web UI 和自动扩缩容但多一层代理网络延迟增加 0.3~0.5msQPS 上限降低约 8%。这笔账必须算清。隐性成本团队熟悉度、学习曲线、故障排查难度。曾有个项目为追求“云原生”强行上 Istio 服务网格结果一次 TLS 证书更新失误导致全站 5 分钟不可用而排查耗时 47 分钟——因为团队没人深入理解 Envoy 的证书加载机制。notes 里明确记下“Istio 引入后P99 故障定位时间从平均 8 分钟升至 35 分钟新增 3 类高频误配置Sidecar 注入策略、Gateway TLS 配置、VirtualService 路由优先级需额外投入 2 人周培训。”演化成本未来半年到两年内业务增长带来的架构调整难度。这是最容易被忽略的。比如消息队列选型Kafka 吞吐无敌但它的 Topic 不支持动态删除需手动清理磁盘如果业务需要频繁创建/销毁临时 Topic如活动弹幕频道运维负担会指数级上升。而 RabbitMQ 的 Topic Exchange 天然支持按需创建虽吞吐稍低但演化成本更低。notes 里会画一张简单的二维坐标图X 轴是当前业务规模QPS/数据量Y 轴是预期增长速率月环比然后标出各候选方案的“舒适区”和“危险区”。这种图不求精确但能强迫你直面“这个选择能撑多久”。2.3 避免“纸上谈兵”的核心机制强制绑定真实场景与量化指标所有脱离具体数字的系统设计都是耍流氓。我的 notes 里绝不允许出现“高并发”“大数据量”“高性能”这类模糊词。取而代之的是“支撑 2000 万注册用户日活 300 万峰值下单 QPS 8500集中在晚 8 点 30 分至 9 点订单平均大小 1.2KB预计年数据增长 15TB”。每一个设计决策都必须锚定在这个基线上。例如设计用户中心的读写分离策略读场景首页 Feed 流需返回用户昵称、头像、关注数、最近动态QPS 12000P95 延迟要求 300ms。写场景用户修改资料昵称/头像QPS 200强一致性要求改完立刻可见。决策推演若用 MySQL 主从 应用层路由从库延迟波动大P95 达 1.2sFeed 流大量展示过期头像用户投诉率预估上升 17%若用 Redis 缓存用户基础信息TTL 设 30 分钟则修改后最长 30 分钟才生效违反强一致要求最终方案MySQL 主库写 Redis 缓存写后双删 本地缓存 Guava CacheTTL 10s用于抗热点。验证压测显示修改资料后Feed 流中头像更新 P95 延迟 8.3s投诉率模型预测下降至 0.3%。这个过程就是 notes 的灵魂——它不告诉你答案它逼你亲手算一遍哪怕算错也要把错误路径记下来。因为下一次你会记得检查“缓存失效窗口”是否覆盖了业务容忍阈值。3. 核心细节解析与实操要点让笔记真正“长”进脑子里3.1 “决策记录”模块不是记结论是记“当时为什么没选它”/decisions目录是 notes 的心脏。但它的写法和常规笔记截然不同。我规定每一份决策记录必须包含且仅包含以下五个部分缺一不可场景快照Snapshot用 3 句话描述当时的业务背景、技术约束、时间压力。“背景618 大促前 3 周订单履约系统偶发超时监控显示库存服务响应 P99 从 120ms 升至 850ms约束不能停机升级DB 已是 RDS 最高规格时间需 5 天内上线。”可选项清单Options列出所有认真评估过的方案哪怕明显不合理。“A. 扩容库存 DBRDS 规格升 2 级B. 在库存服务前加 Redis 缓存缓存库存扣减结果C. 将库存扣减逻辑下沉至 MySQL 存储过程D. 引入本地缓存 CaffeineTTL 1s。”否决理由Why Not对每个被否决的选项写明一条不可逾越的硬伤。“A. 否决RDS 升级需 4 小时维护窗口大促期间禁止B. 否决缓存库存扣减结果会导致超卖缓存击穿时多个请求同时扣减同一库存C. 否决RDS 不支持复杂存储过程且违背应用层逻辑自治原则。”选定方案Chosen清晰描述最终方案及关键参数。“D. 采用 Caffeine 本地缓存key 为sku_id:warehouse_idvalue 为stock_countTTL 严格设为 1000ms非默认 1s因库存变更频率实测为 800ms 一次缓存命中率目标 92%。”验证结果Proof上线后 24 小时的真实数据。“上线后 24h库存服务 P99 响应降至 142ms缓存命中率 93.7%大促峰值期零超时。附 Grafana 截图链接。”提示这个模板的威力在于它强迫你暴露思考盲区。很多人写“否决理由”时会发现“B 方案会导致超卖”这个点自己之前根本没意识到——这就是认知提升的起点。我坚持写了 4 年现在看到新需求大脑会自动启动这个五步框架比翻笔记还快。3.2 “权衡分析”模块用表格把抽象概念钉死在业务现实上/tradeoffs目录专治“听起来都好但不知道选哪个”的纠结症。它的核心是一张动态表格横轴是业务指标纵轴是技术方案单元格里填的不是“优/良/差”而是具体的、可测量的数值变化。以“API 网关选型”为例我们对比 Kong、APISIX、Spring Cloud Gateway评估维度Kong (v3.4)APISIX (v3.5)Spring Cloud Gateway (v4.1)P99 请求延迟1.8ms启用 JWT 插件后1.2ms启用 WAF 插件后3.5ms启用 Hystrix 熔断后万级路由配置热加载时间8.2s需 reload nginx 进程0.3setcd 实时监听12s需重启 JVM插件开发门槛Lua团队 2 人天可上手Lua Go需 1 周熟悉 SDKJava现有后端团队 0 学习成本故障隔离粒度进程级单个 Kong 实例挂影响其路由Worker 级单个 worker 挂不影响其他JVM 级整个网关实例挂月度运维成本估算$1200托管版 License 2c4g * 3$450开源版 2c4g * 2$0开源 复用现有 Kubernetes 资源这张表的价值不在于告诉你“APISIX 最好”而在于让你看清如果你的业务路由变更极其频繁每天上百次那么 Kong 的 8.2s reload 时间就是致命伤如果你的团队全是 Java 工程师强行上 Lua 生态人力成本可能远超 License 费用。notes 里这张表会持续更新——当某次线上事故暴露了某个维度的严重缺陷如“Kong 在高并发下 JWT 解析 CPU 占用飙升至 95%”我会在对应单元格追加红色批注“⚠️ P99 延迟在 5000 QPS 下跃升至 15ms需紧急优化或降级”。这种动态记录让笔记真正成为团队的“集体记忆”。3.3 “故障模式推演”模块在纸上“杀死”你的系统/failure-modes是 notes 中最烧脑也最实用的部分。它不做“如果 Redis 挂了怎么办”的泛泛而谈而是进行原子级故障注入。我的标准流程是锁定一个核心组件如订单服务的 MySQL 主库定义单一故障类型如主库网络分区导致从库晋升为新主原主库恢复后成为从库沿着数据流逐环节推演应用层MyBatis 是否配置了failFastfalse连接池是否会因超时不断重连旧主中间件ShardingSphere 的读写分离策略是否将写请求错误路由到旧主此时旧主已是只读数据层GTID 复制是否开启若未开启旧主恢复后 binlog 位置错乱是否导致从库复制中断量化影响影响范围多少比例的订单创建请求失败实测37%恢复时间从故障发生到全量服务恢复MTTR 是多少实测12 分钟其中 8 分钟用于人工校验数据一致性数据损失是否有订单丢失或重复实测0 丢失但 2 笔订单状态异常需人工干预注意推演必须基于你真实的配置。我见过有人推演“Kafka 磁盘满”却忘了自己集群启用了log.retention.hours1687 天而实际业务日志量只需 3 天就占满磁盘——这种脱离实际的推演毫无意义。每次推演后我会在对应组件的配置文件旁贴一个// [FMEA] 2023-10-15: 磁盘满时broker 会拒绝新消息producer 报NotEnoughReplicasException需监控kafka_server_broker_topic_metrics_log_dir_size_bytes 。这才是笔记该有的样子它不是知识的终点而是行动的起点。3.4 “规模基准测试”模块用数字撕掉“理论上可行”的遮羞布/scale-benchmarks目录存放所有压测报告的原始数据和关键结论。但重点不是“QPS 多少”而是在什么条件下达到这个 QPS。一份合格的 benchmark 记录必须包含环境基线“测试机4c8g * 3JMeter被测服务2c4g * 4K8s Pod网络同 VPC 内网延迟 0.2ms”。数据集特征“用户表1 亿行索引字段user_id主键、status普通索引status值分布active95%,inactive5%”。压测脚本关键逻辑“模拟真实用户行为80% 请求查user_id15% 请求查statusactive5% 请求查statusinactive冷查询”。核心发现“当statusinactive查询占比从 5% 升至 10% 时QPS 从 12000 断崖式跌至 3200P99 延迟从 45ms 升至 2100ms。根因status索引选择性差MySQL 优化器弃用索引全表扫描。解决方案为statusinactive创建单独的冗余表或改用位图索引Bitmap Index”。这个模块教会我的最重要一课是没有银弹只有适配。同一个 MySQL 配置在“查活跃用户”场景下性能卓越在“查休眠用户”场景下就是灾难。notes 的价值就是把这些残酷的适配关系用数字赤裸裸地刻下来让你下次设计索引时手指悬在键盘上会本能地想起那个 2100ms 的 P99 延迟。4. 实操过程与核心环节实现从零搭建你的 system-design-notes 仓库4.1 仓库初始化用最小可行结构启动别一上来就规划宏大的目录树。我的建议是用 15 分钟完成一个绝对够用的 MVP 结构。打开终端执行mkdir system-design-notes cd system-design-notes git init echo # System Design Notes - My Thinking Lab README.md mkdir -p decisions tradeoffs failure-modes scale-benchmarks touch decisions/TEMPLATE.md tradeoffs/TEMPLATE.md failure-modes/TEMPLATE.md scale-benchmarks/TEMPLATE.md git add . git commit -m chore: init repo with core dirs and templates现在你的仓库里只有 5 个文件README.md和 4 个模板文件。TEMPLATE.md的内容就是上一节讲的“决策记录五要素”、“权衡分析表格”等标准化格式。关键动作立刻打开decisions/TEMPLATE.md把它改成你最近遇到的一个真实设计难题。比如如果你今天在纠结“用户登录态用 JWT 还是 Session”那就把它填进去。不要追求完美先完成。这个“完成”的动作比写一百页漂亮笔记都重要——它建立了“笔记即实践”的心理契约。4.2 日常维护把笔记写进工作流而非工作后最大的误区是把写 notes 当成额外任务堆在下班后。这注定失败。我的做法是让笔记成为开发流程的自然产出物。具体嵌入点Code Review 时当同事的 PR 引入了一个新组件如首次接入 Elasticsearch我在 CR 评论里不只写“LGTM”而是追加“张三 请在/decisions/2024-05-es-integration.md中补充本次选型的Why Not尤其对比了 OpenSearch 的哪些点”。线上故障复盘会Postmortem后会议结束 1 小时内必须在/failure-modes/下新建一个文件标题为YYYY-MM-DD-[服务名]-[故障简述].md内容直接粘贴会议纪要中的“根因分析”和“改进项”并标注负责人和截止日期。压测报告邮件发出前把报告里的核心图表、关键结论、配置参数直接复制到/scale-benchmarks/YYYY-MM-DD-[场景名].md中并用引用块标出“ 关键洞察当并发用户数超过 8000连接池耗尽错误率陡升。建议将maxActive从 100 调至 200并增加连接泄漏检测”。实操心得我设置了一个 GitHub Action每当向decisions/目录推送新文件就自动触发一条 Slack 通知发送到团队频道“ 新决策记录/decisions/2024-05-20-payment-gateway-switch.md请相关同学查阅”。这看似小动作却让笔记从“个人备忘录”变成了“团队知识契约”大家会不自觉地去翻、去评论、去补充。知识一旦流动起来它就活了。4.3 工具链整合让笔记自动“呼吸”纯文本笔记容易沉睡。我的方案是让它与生产环境数据联动监控告警联动用 Prometheus Alertmanager 的 webhook将特定级别告警如MySQL_Above_90_Percent_Disk_Usage自动创建一个/failure-modes/YYYY-MM-DD-disk-full-mysql.md文件内容包含告警时间、指标值、关联的 Grafana Dashboard 链接。这确保了“故障推演”永远基于最新发生的痛点。CI/CD 流水线嵌入在 Jenkins 或 GitLab CI 的部署脚本末尾添加一步curl -X POST https://api.github.com/repos/your-org/system-design-notes/contents/scale-benchmarks/$(date %Y-%m-%d)-$(git rev-parse --short HEAD).md -H Authorization: token $GITHUB_TOKEN -d {message:auto-commit benchmark from CI,content:$(base64 -w 0 ./benchmark-report.json)}。这样每次上线最新的压测数据就自动归档。文档即代码Docs as Code用 MkDocs Material for MkDocs 将 notes 仓库渲染成内部 Wiki。关键技巧在mkdocs.yml中配置plugins启用git-revision-date-localized让每页底部自动显示“最后更新于2024-05-20Git 提交时间”。这无声地传递一个信息这里的知识和代码一样是活的、可追溯的、有版本的。4.4 知识沉淀从个人笔记到团队“设计宪法”当你的 notes 积累到 50 份决策记录时就该启动第二阶段提炼“设计宪法”。这不是写规范文档而是做模式识别。我用 Python 脚本定期扫描所有decisions/*.md文件提取关键词如cache,consistency,latency,cost统计它们在“否决理由”中出现的频次。结果惊人consistency出现在 73% 的否决理由中而latency仅占 12%。这意味着我们的团队在权衡时一致性是绝对红线延迟是可妥协项。于是我起草了第一条“宪法”《一致性优先原则》任何架构设计若存在导致强一致性破坏的风险如最终一致性方案用于资金类操作必须提供经验证的、自动化的补偿机制并通过混沌工程验证其有效性。未经此验证的方案禁止上线。第二条来自/failure-modes/的高频故障《网络分区生存原则》所有跨服务调用必须预设网络分区场景。默认策略为“快速失败”Fail Fast而非无限重试。重试逻辑必须限定次数≤3 次和总超时≤2s并记录重试日志供事后分析。这些“宪法”不是挂在墙上的口号而是嵌入到代码审查 Checklist 中的硬性条款。当新人提交 PRCR Bot 会自动检查“是否在支付回调接口中实现了幂等性校验依据《一致性优先原则》第 1.2 条”。笔记就这样完成了从“个人思考痕迹”到“团队设计基因”的蜕变。5. 常见问题与排查技巧实录那些没人告诉你的坑5.1 问题笔记越写越多但面试/设计时还是想不起来现象仓库里有 200 个文件搜索关键词能立刻找到但临场发挥时大脑一片空白。根因分析笔记停留在“信息存储”层未进入“认知提取”层。大脑不是硬盘它靠模式和线索检索而非关键词。排查与解决立即行动打开你的 notes 仓库随机选 5 个decisions/文件不看内容只看文件名如2023-11-user-id-snowflake.md然后闭眼 30 秒尝试回忆当时什么业务场景否决了哪两个方案为什么如果回忆不出说明这个记录对你而言只是“存档”不是“记忆”。重构策略为每个核心决策手写一张 A6 纸卡片正面写场景和问题背面只写三个关键词如“618 大促”、“库存超卖”、“本地缓存 TTL 1s”。每周抽 10 张像背单词一样复习。实测坚持 3 周临场反应速度提升 2 倍。终极技巧每月最后一个周五下午关闭所有电脑用白板和马克笔给一位同事最好是前端或测试讲清楚你本月最重要的一个设计决策。要求不看笔记不提技术名词只用业务语言如“为了让用户抢到限量商品我们让系统记住每个商品还剩多少但这个数字不是实时的而是每 1 秒刷新一次所以最多可能多卖 1 件”。讲不通的地方就是你笔记里没真正想透的点。5.2 问题团队协作时笔记变成“吵架现场”大家各执一词现象/tradeoffs/表格里Kong 和 APISIX 的评分被不同人反复修改评论区变成辩论赛。根因分析缺乏统一的评估标尺。A 认为“Lua 简单”B 认为“Go 更安全”争论永远无解。排查与解决建立“标尺委员会”由架构师、资深开发、SRE 各 1 人组成每季度开会发布《技术评估标尺 v1.2》。标尺不是主观打分而是定义客观测量方法。例如“开发效率”标尺 “从需求提出到第一个可测试 demo 上线所需人天”并规定测量方式必须用 Jira 工时日志统计。强制“数据说话”任何对表格的修改必须附带原始数据链接如 Grafana 快照、压测报告 URL、代码仓库 commit hash。没有数据支撑的修改会被 Bot 自动 Revert。引入“沉默期”当一个重大决策如更换消息队列被提出进入/decisions/目录后自动开启 72 小时“沉默期”——期间禁止评论只允许提交实证数据压测报告、PoC 代码、竞品文档链接。72 小时后所有人基于同一份数据集讨论。这个规则让讨论从“我觉得”变成“数据显示”。5.3 问题笔记内容太“干”新人看了直呼“看不懂”老手觉得“太浅”现象/failure-modes/里写“MySQL 主从延迟导致读到脏数据”新人问“什么是主从延迟”老手吐槽“这谁不知道”。根因分析笔记缺乏“上下文锚点”没有标明读者的认知基线。排查与解决实施“三级注释”在每份笔记开头用 YAML Front Matter 标明--- audience: - junior: 需了解 MySQL 基础语句和主从概念 - senior: 需熟悉 binlog 复制原理和 GTID prerequisites: - 阅读 /scale-benchmarks/2023-09-mysql-replication-lag.md - 实验 /failure-modes/2023-08-network-partition-simulate.md ---插入“小白快问”在技术细节旁用 小白快问引用块回答最朴素的问题。“ 小白快问为什么主从延迟会导致读到脏数据答想象你转账后立刻查余额应用连的是从库但钱还没从主库同步过来所以看到的还是旧余额。就像你发微信说‘到了’朋友手机还没收到消息以为你还在路上。”提供“老手深潜”链接在关键结论后用[深入原理]链接到外部权威文档或论文。“最终方案采用 Canal 监听 binlog 深入原理 ”。5.4 问题笔记更新滞后线上已用新方案notes 还是旧的现象某次紧急上线了新缓存策略但/decisions/里对应的文件半年没更新。根因分析笔记更新未纳入发布流程成了“可选项”而非“必选项”。排查与解决发布流水线门禁在 CI/CD 的最后一步部署到生产环境前添加一个检查脚本# 检查本次 PR 是否修改了 /decisions/ 或 /failure-modes/ 目录 if git diff --name-only HEAD^ | grep -qE ^(decisions|failure-modes)/; then echo ✅ 笔记已更新准予发布 else echo ❌ 错误本次架构变更未更新 system-design-notes请补充 /decisions/2024-05-xx-new-cache-strategy.md exit 1 fi设立“笔记守护者”轮值团队每人每月轮值一周职责是1扫描所有新上线服务确认 notes 是否更新2对未更新的发起 PR 并 相关负责人3整理本周所有笔记更新发到团队群。轮值表公开在 Wiki 首页。奖励“更新王”每月评选“笔记更新最及时奖”奖励不是奖金而是一本签名版《Designing Data-Intensive Applications》扉页写“致 XX你让团队的设计智慧始终在线”。最后分享一个小技巧我所有的 notes 文件都用 Obsidian 的[[ ]]语法互相链接。比如在decisions/2023-11-user-id-snowflake.md里会写“此方案的故障模式见 [[failure-modes/2023-11-snowflake-clock-drift]]”。Obsidian 会自动生成双向链接图谱。当我点开这个图谱看到snowflake节点周围密集连接着failure-modes、scale-benchmarks、tradeoffs那一刻我看到的不是一个孤立的技术点而是一个活的、呼吸的、有血有肉的系统设计认知网络。这才是 system-design-notes 的终极形态——它不是你写的笔记它是你思考能力的外延。
