接手陌生模块，最常见的两天是这样过的：从 controller 往下翻，翻到 service 看见二十个方法，挑看起来最重要的三个读，中途跳进一个不认识的工具类，跳回来已忘了上下文。两天后能画出半个调用图，被问"要改这里该动哪"，答不上来。
问题不在速度。读得快救不了顺序错误——顺序错了，速度只是让你更快地迷路。第一步不是打开文件，是确定"我要回答哪个问题"。半天的合格线不是"读完"，而是能答三个问题：对外承诺了什么、谁在依赖它、数据从哪来到哪去。
1. 顺序：五种读法各自适合回答什么
| 读法 | 起点 | 半天能得到的产物 | 什么时候失效 |
|---|---|---|---|
| 自顶向下 | 对外暴露的接口 | 能力边界清单 | 一个接口挂着十几个实现，或入口由框架生成 |
| 自底向上 | 有测试覆盖的最小单元 | 数据结构的真实形态 | 模块没有测试，核心逻辑在编排层 |
| 沿调用链 | 一次真实请求 | 端到端路径 | 链路断在消息队列或定时任务里 |
| 沿数据流 | 表结构与 DTO | 字段的来龙去脉 | 同一份数据有多个写入点，没有单一入口 |
| 沿变更历史 | git log 与 MR |
设计意图与历史决策 | 仓库被 squash 过，或代码是搬来的 |
自顶向下适合"要加一个能力"，自底向上适合"要改一个行为"，沿调用链适合"线上出问题"。选错的典型症状是：只想加一个字段，却把整个 service 读了一遍。
自底向上在调试时往往更有效：调试手上有一份确定证据（栈、错值、日志），它天然指向最小单元，顺着它往外扩两层就能看清谁在摆布它。从入口自顶向下读，则会把与 bug 无关的九条路径一起读进去。
─── 半天的阅读路线：按问题选起点，不按目录结构走
问题 A 对外承诺了什么 → 接口定义 + 参数校验 + 错误码
问题 B 谁在依赖它 → 调用方检索 + 上游超时与重试配置
问题 C 数据从哪来到哪去 → 表结构 + 写入点 + 序列化边界
// 三个问题都有答案，才允许进入实现细节；否则先补缺口
2. 三个必读入口
| 入口 | 怎么找 | 回答什么 | 漏掉的代价 |
|---|---|---|---|
| 对外暴露的接口 | 路由注册处、接口定义、MQ 的 topic 名 | 能力边界与契约 | 把内部实现当契约改，改完才发现有外部调用方 |
| 被谁调用 | 全仓检索符号名，再检索配置里的地址与 topic | 影响面 | 动了一个"内部方法"，结果扫到三个业务方 |
| 数据从哪来到哪去 | 表结构、写入点、缓存键、序列化边界 | 状态的真身 | 在 DTO 层推理，实际字段在 DB 里被别的写入路径改过 |
顺序有讲究：先接口，再调用方，最后数据。接口定承诺，调用方定影响面，数据定状态。反过来先在字段命名上耗半天，而那些字段有一半已没有写入方。
// 入口一：先看注册了什么，而不是先看实现了什么
grep -rn "RequestMapping\|PostMapping\|@Path" src/main --include=*.java
// 入口二：谁在调我（含跨仓、配置里的地址）
grep -rn "OrderService\|order-service\|order\.settle" --include=*.{java,yml,properties} .
// 入口三：数据落点，写入点往往比你预计的多
grep -rn "insert into\|save(\|updateById(" src/main --include=*.java | head -50
grep 出来的调用方分两类记：编译期依赖（改签名会断）与运行期依赖（配置里的地址、MQ 订阅关系）。后者最容易漏，因为它在代码里根本不存在。
3. 采样：跳过细节比读懂细节更重要
"读懂每一行"是最慢的读法，还会给虚假的完成感：读完一个 800 行的类感觉掌握了，被问"订单已取消时这条路径怎样"就答不上来——你读的是语句，不是判断。
| 读 | 跳 | 判据 |
|---|---|---|
| 方法签名、返回类型、抛出的异常 | 方法体里 80% 的顺序语句 | 签名是契约，方法体是本次实现 |
| 分支条件与状态机转移 | 循环里的下标细节 | 决定走哪条路的判断才影响你的改动 |
| 错误处理与降级路径 | 日志文案与埋点 | 出错时的行为就是失效边界 |
| 与外部交互的点（DB、HTTP、MQ） | 内部纯函数 | 交互点决定延迟与一致性 |
| 测试用例名 | 断言的逐行实现 | 用例名常是唯一准确的需求描述 |
| 配置文件的生效值 | 默认值旁的注释 | 生效值才是事实，注释只是意图 |
采样的标准只有一条：这条信息会不会改变你的下一步动作。不会改变的，跳过。这条标准能砍掉大部分阅读量，且砍得有据：注意力是按决策价值分配的。
─── 三遍读法：每遍只回答一个问题，不回头补
第 1 遍 20 分钟：只看签名、注解、常量 → 有哪些角色、边界在哪
第 2 遍 40 分钟：只看分支与外部调用 → 主路径、旁路、失败路径
第 3 遍 按需：只逐行读你要改的那一段
// 反例：第 1 遍就逐行读，到第 3 遍时上下文已被细节冲掉
4. 可信度排序与运行时校正
| 证据 | 可信度 | 过期速度 | 怎么用 |
|---|---|---|---|
| 命名（类名、方法名、字段名） | 高 | 慢 | 先按名字建立假设 |
| 结构（调用关系、分层、依赖方向） | 高 | 慢 | 用结构检验命名有没有说谎 |
| 测试用例 | 中高 | 中 | 用例名当需求读，断言当行为读 |
| 运行时日志与调用链 | 高（仅当下） | 快 | 校正文本理解的硬证据 |
| 注释 | 低 | 最快 | 只用来解释"为什么"，不用来解释"是什么" |
| 提交信息与 MR 描述 | 中 | 中 | 找历史决策，尤其找"为什么不能那样改" |
排序压成一句：命名 > 结构 > 测试 > 注释。注释不在编译期被检查，也没人改代码时同步更新；一条三年前的注释比没有注释更危险，它让你相信一个已不存在的前提。
进入实现之前，对每个要动的代码块问三个问题：
| 问题 | 想不清的后果 |
|---|---|
| 这段代码负责什么决定 | 分不清业务规则与技术权宜，改错层 |
| 它依赖什么假设 | 假设不成立时，改动在测试环境正常、生产静默出错 |
| 出问题时谁先炸 | 不知道失效点，就选不出该加什么监控 |
第三个问题最易被跳过也最值钱：它把阅读接到可观测性上。凡是"炸了没人知道"的地方，就是该动的第一处。
─── 文本理解与运行时证据冲突时，以运行时为准
1) 入口打一条日志：入参、用户标识、trace id
2) 疑似分支各打一条：只记走了哪条路，别打变量全集
3) 触发一次真实请求，日志顺序即真实调用顺序
4) 断点只下在准备改的那一行，别下在入口
// 常见发现：配置开关是关的，那段"核心逻辑"一行没跑
5. 交付物与收益上限
阅读结果不落成文字，三天后只剩"我好像看过"。也不必写成长文，一页卡就够——超过一页通常说明还没读懂，只是在抄代码。
─── 模块阅读卡：一页，写不满说明还有缺口
module: order-settlement
entry: [POST /api/settle, topic settle.retry]
calls_out: [account-service, coupon-service, mq:settle.result]
owns: [settle_task, settle_item]
// 关键假设，改动前逐条确认，不要凭印象
assumptions:
- A1 // 调用方一定先落 settle_task，否则幂等键取不到
- A2 // coupon 超时上限按配置读取，本地重试 3 次会放大等待
// 失效点，按爆炸顺序排
fail_first: [coupon 超时, 幂等键重复, 金额精度]
open_questions: [为何有两条写入路径, 老版本兼容字段谁在用]
| 阅读能给你 | 阅读给不了你 |
|---|---|
| 能力边界与影响面 | 为什么长成这样（要问人、看历史） |
| 关键假设与失效点 | 真实风险（要跑一次才知道） |
| 该改哪一层的定位 | 改对（要动手、要验证） |
最后一行是收益上限：读代码能建立理解，不能替代动手改。读的边际收益几小时后急剧下降，剩下的理解只能靠一次真实改动换来。能说清三个问题、列出假设、指出失效点，就动手。
| 度量 | 怎么量 | 说明 |
|---|---|---|
| 首次提改动的时间 | 接到任务到第一个可评审 diff | 按半天记，别精确到小时 |
| 读后预测命中率 | 先写"改这里会影响 X"，改完核对 | 低于一半说明读的是语句 |
| 求助次数 | 同一模块第二次接手时还问几次 | 降到 1–2 次算读完 |
| 阅读卡被引用次数 | 别人改这块时有没有翻你的卡 | 唯一能证明产物有用的指标 |
6. 排错与边界
| 现象 | 更可能的原因 | 处理 |
|---|---|---|
| 读了两天不知从哪进 | 缺业务上下文，不是缺代码能力 | 找一段真实请求或工单，从现象倒推 |
| 每个方法都懂，合起来不懂 | 缺历史决策 | 翻 git log 与被删掉的分支，找"为什么不能那样做" |
| 代码确实乱，越读越乱 | 命名与结构已经失效 | 停止通读，改成"只读要改的那一行 + 先补测试" |
| 读完的预测全错 | 配置或开关让实际路径与代码不符 | 用运行时证据校正，别改代码去迁就理解 |
| 一改就炸，炸在别处 | 关键假设没列出来 | 补 assumptions，逐条找反例 |
"读不懂"的三个真实原因里，两个不在代码上：缺业务上下文、缺历史决策，第三个才是代码确实乱。把前两个当成第三个处理，就会生出"重写一遍就懂了"的冲动，而重写只会把历史决策一起丢掉。
| 场景 | 做法 | 理由 |
|---|---|---|
| 模块只有几百行 | 直接通读 | 采样开销大于通读 |
| 即将废弃或替换 | 只读接口与数据边界 | 理解内部实现没有回报 |
| 只读一次、后续不改 | 只读入口与错误路径 | 系统化阅读是投资，要有复用场景 |
| 文档刚更新过且有人维护 | 信文档 + 抽查两处 | 抽查只为确认没过期 |
| 手上只有一小时 | 只回答"谁在调用我" | 影响面是唯一不能猜的东西 |
7. 自测
- "加字段"的需求该从哪个入口开始读，为什么不是从表结构？
- 调试时为什么自底向上常常比自顶向下省时间？
- 一条三年前的注释，什么时候可以信、什么时候必须验证？
- "读懂每一行"为什么会制造虚假的完成感？
- 阅读卡的
fail_first与可观测性是什么关系？ - 什么情况下，系统化阅读法反而是负担？