跳到主要内容

the-missing-readme 拆解大纲(12 章)

切分口径:按推理链与新词密度切,不按字数。原书 14 章正文约 19.3 万字符; 我们的拆解 12 章,预估总量 ≥ 原书正文(样板倍率约 1.0-1.2x:本书机制密度低、 判断密度高,原书已自带大量故事,我们补的是术语解释、走查和台阶,不是压缩原书)。

主线一句话:一个会写代码的毕业生,沿一条有站点的路线走到「能独立负责一个系统、 能对下一步怎么走做判断」——每一章给这条路铺一段。

大纲(一节一行:「进来时以为…→出去时知道…」)​

01-starting-line.md(原书 ch01+ch02)起点:地图、学习与提问​

  • 节 1:进来以为入行主要缺技术 → 出去知道缺的是「学校不教的那一半」,且第一课是承认自己处在「有意识的无能力」(四阶段模型)。
  • 节 2:进来以为成长靠多干活 → 出去知道学习本身是个工程问题,有 7 种可选择的手段,且不许全上(会倦怠)。
  • 节 3:进来以为提问是打扰别人 → 出去知道提问是可设计的:调查→时限→写全过程,加上组播异步等「非打扰」通道。
  • 节 4:进来以为自信/自卑是性格 → 出去知道冒充者综合征与邓宁-克鲁格是两个可识别、可反制的循环。
  • 主走查:潘卡那条提问邮件(坏版 vs 好版),走「调查→时限→写全过程」三步。

02-inherited-code.md(原书 ch03)接手别人的代码​

  • 节 1:进来以为乱代码是前人不行 → 出去知道熵是变化的自然副作用,债甚至可能是项目活下来的标志。
  • 节 2:进来以为技术债=不喜欢的代码 → 出去知道债有本金利息与 2×2 矩阵,乱用这个词会稀释它。
  • 节 3:进来以为改代码=写代码 → 出去知道安全变更的五步(先立栅栏再动土)与童子军原则。
  • 节 4:进来以为新技术=进步 → 出去知道创新代币、保守选型与「十倍好」门槛,以及重写的真实代价(DDG:6 个月变 18 个月)。
  • 主走查:约翰娜的登录服务(On-Call 问题 30%+)走「债务提案模板」五步;Java 缺大括号代码用具体数值走异味判定。

03-production-ready-code.md(原书 ch04)写出能在生产环境活下来的代码​

  • 节 1:进来以为代码写完=交付 → 出去知道生产环境会攻击代码,代码要自带保护、诊断、控制三层。
  • 节 2:进来以为防御=多写 if → 出去知道防御从类型与不可变开始,异常有完整的纪律(精确/早抛晚捕/不吞)。
  • 节 3:进来以为出错重试就行 → 出去知道重试要退避+抖动,而幂等(唯一 ID)才是治本。
  • 节 4:进来以为日志=print → 出去知道级别/原子性/性能/敏感数据四件事,以及监控三件套与 P99。
  • 节 5:进来以为配置是小事 → 出去知道配置即代码、默认值、校验,以及为什么不许在凌晨 3 点手改生产配置。
  • 主走查:书中 StatsD Flask 应用四个指标(key_hit/key_miss/gauge/timer)逐个落位;幂等用计费重试的 10 元→20 元走一遍。

04-dependencies.md(原书 ch05)依赖:借来的代码​

  • 节 1:进来以为加依赖是白拿 → 出去知道 left-pad 一夜拆掉成千上万项目,每个依赖都是租约。
  • 节 2:进来以为版本号是装饰 → 出去知道 SemVer 三段号各自承诺什么、0.x 为什么不算数。
  • 节 3:进来以为依赖树只一层 → 出去知道传递依赖(1→101)与钻石/循环依赖如何引爆。
  • 节 4:进来以为 DRY 万岁 → 出去知道隔离(复制/供应商/遮蔽)与 pinning/依赖清单是防地狱的手段。
  • 主走查:Gradle 依赖树(代码清单 5-2/5-3):httpclient 拉 3 个传递依赖→加 util 引爆 slf4j 1.6.1 vs 1.7.21 的钻石冲突→-> 标记裁决。

05-testing.md(原书 ch06)测试:按风险买保险​

  • 节 1:进来以为测试=证明代码对 → 出去知道测试五用途,以及它是接口设计的第一个读者(TDD)。
  • 节 2:进来以为测试只有一种 → 出去知道单元/集成/系统/性能/验收的分层与各自的快慢取舍。
  • 节 3:进来以为工具越多越好 → 出去知道每个工具都有成本;模拟库过度=紧耦合异味。
  • 节 4:进来以为覆盖率=质量 → 出去知道覆盖率只是指南(100% 也能藏 bug),该按风险矩阵分配力气(沿用 BOOK-TEARDOWN 既有口径)。
  • 节 5:进来以为测试抖动是运气 → 出去知道拍打测试有 9 个确定来源与 9 个修法(种子/注入时钟/0 端口/唯一路径/清状态…)。
  • 主走查:SimpleThrottler 从「系统时钟」改成「注入时钟」,用具体毫秒数走 500ms 边界为什么忽过忽挂。

06-code-review.md(原书 ch07)代码评审:一台双向学习机器​

  • 节 1:进来以为评审=挑错 → 出去知道五重价值,以及一切好处的共同前提是「高度信任」。
  • 节 2:进来以为提交评审=发链接 → 出去知道一份好评审请求的构造(标题/描述/检查列表)与草案、预排。
  • 节 3:进来以为评审者是关卡 → 出去知道评审者的纪律:先懂意图、区分问题/建议/挑剔、推动决断不当橡皮图章。
  • 节 4:进来以为被批评=被否定 → 出去知道意见对代码不对人,冲突有升级路径(提交者/负责人/法定人数)。
  • 主走查:UI-1343 评审请求样例逐字段拆;端口校验评论的差版 vs 好版。

07-delivery.md(原书 ch08)软件交付:从 Git 提交到真实用户​

  • 节 1:进来以为「发布」一个词 → 出去知道构建/发布/部署/展开四阶段各有各的事,术语先对齐。
  • 节 2:进来以为分支随便切 → 出去知道主干式+CI 与 Gitflow 的取舍(且 Gitflow 作者已不再推荐)。
  • 节 3:进来以为部署=上线 → 出去知道部署只是安装;展开才碰用户,而展开有一整套降险模式。
  • 节 4:进来以为回滚靠祈祷 → 出去知道特性开关/熔断器/金丝雀(1%)/蓝绿/摸黑启动各自的机制与代价。
  • 主走查:一个带版本号的 deb 包从构建到金丝雀 1% 流量的全程;幂等原子部署用「装新目录+软链接翻转」走一遍。

08-oncall.md(原书 ch09)On-Call:事故响应的完整流程​

  • 节 1:进来以为值班=修 bug → 出去知道值班是一项技能包:响应/专注/优先级/沟通/跟踪。
  • 节 2:进来以为处理事故=找根因 → 出去知道顺序错了:先分流定级、再协同、再止血(应急),根因排第三。
  • 节 3:进来以为修完就完了 → 出去知道后续行动(回顾/5 Why/行动项)才是事故的价值所在,且对事不对人。
  • 节 4:进来以为响应快=好工程师 → 出去知道「救火英雄」对团队是毒药(打断深耕、掩盖系统问题、倦怠)。
  • 主走查:数据仓库缺数事故全程(30 流二分法→单键空值头→APM 注入→禁用头解码→5 Why 五连问)。

09-design.md(原书 ch10)技术设计:把模糊想法变成可评审的文档​

  • 节 1:进来以为设计=坐下来画架构图 → 出去知道设计是螺旋:探索与写作交替,信心逐步上升。
  • 节 2:进来以为需求是给的 → 出去知道问题要自己定义(「不解决会怎样?」是裁剪刀),定义完方案可能整个换掉。
  • 节 3:进来以为文档=交付物 → 出去知道写作本身是思考工具(暴露你不知道的东西),且有两个腐烂陷阱。
  • 节 4:进来以为评审=等批准 → 出去知道流程有重(架构评审)轻(RFD)两档,而「不要让人惊讶」比格式更重要。
  • 主走查:库存目录特性请求(扫描+ML 模型)被四个提问改写成完全不同的问题陈述(SKU/Excel/优先级)。

10-evolvable-architecture.md(原书 ch11)可演进的架构:与复杂性讨价还价​

  • 节 1:进来以为复杂=代码多 → 出去知道复杂性的三个可判定的症状(高依赖/高隐蔽/高惯性)。
  • 节 2:进来以为为未来写抽象是远见 → 出去知道 YAGNI/最小惊讶/领域封装才是让明天好改的手段。
  • 节 3:进来以为改 API 就是改函数 → 出去知道向前/向后兼容的精确含义,以及「必填项永远存在」的教训。
  • 节 4:进来以为数据无所谓 → 出去知道 schema 是数据的 API:隔离、显式、迁移工具、下游兼容(ETL/CDC)。
  • 主走查:gRPC Greeter 的 favorite_number 三次演进(required email→sint32→新增字段序号),每次用具体消息走兼容性判定。

11-planning.md(原书 ch12)敏捷计划:团队的节奏​

  • 节 1:进来以为敏捷=流程 → 出去知道宣言只有四行价值观,而流程崇拜恰恰违背第一条。
  • 节 2:进来以为排期=领导拍板 → 出去知道用户故事/验收标准/故事点(相对大小+斐波那契)如何让预估可讨论。
  • 节 3:进来以为会议是开销 → 出去知道站会(15 分钟仪表盘)/评审(展示工作)/回顾(修流程)各自回答不同的问题。
  • 节 4:进来以为计划是承诺 → 出去知道路线图是「无用的计划但不可缺少」,更近更准、更远更糊。
  • 主走查:postProfile 重试参数从用户故事到上线的分解(6 步),套进 4 人×10 点=40 点的冲刺容量。

12-manager-and-career.md(原书 ch13+ch14)管理者与职业阶梯​

  • 节 1:进来以为管理者=分配任务的人 → 出去知道TA做的是人/产品/流程三件事,是你职业成长的第一杠杆。
  • 节 2:进来以为 1:1=汇报会 → 出去知道你定议程、谈大局/反馈/职业,反复被取消本身就是信号。
  • 节 3:进来以为 OKR/绩效是 HR 仪式 → 出去知道关键结果≠待办清单(奶奶聚会例)、60%-80% 的预期、以及用 PPP 存档重建自评。
  • 节 4:进来以为反馈看缘分 → 出去知道 SBI 框架(情况/行为/影响)可复制,且要私下、冷静、频繁。
  • 节 5:进来以为晋升=熬年头 → 出去知道阶梯的两个过渡、T 型技能、主导晋升、胶水工作的陷阱,以及睡眠也是职业策略。
  • 主走查:一年后的绩效自评,用 PPP 存档+OKR 例(99.99%/P99<20ms)+SBI 例逐件重建。

自查(第一律:任意两行「出去时知道」不是同一件事)​

  • 01-节 2(学习方法)与 01-节 3(提问)不同:前者管输入,后者管求助通道。
  • 02-节 3(变更五步)与 05-节 1(测试用途)不同:前者是改码流程,后者是测试的定位;测试机制全在 05。
  • 03-节 3(重试/幂等)与 08-节 2(应急止血)不同:前者是代码层机制,后者是组织层流程,07/08 交叉引用但不重复讲。
  • 07-节 4(展开模式)与 10-节 3(API 兼容)不同:前者是流量策略,后者是兼容性约束;10 讲为什么展开需要兼容,07 不展开讲。
  • 11-节 3(会议)与 12-节 2(1:1)不同:前者是团队节奏,后者是一对一关系。
  • 12-节 5(晋升)与 index 主线落点一致:全书终点=对「下一步怎么走」有判断。
  • 原书每一章都被覆盖:ch01+02→01,ch03→02,ch04→03,ch05→04,ch06→05,ch07→06,ch08→07,ch09→08,ch10→09,ch11→10,ch12→11,ch13+14→12。✓(12 章,超出预估的 8-11 上限 1 章,理由:ch12 敏捷与 ch13/14 人事侧是两条推理链,合并会超 3 万字符且配额爆炸;ch01 太薄不足以独立成章,已并入 01。)