只读优先：第一次跑目标系统前先做只读验证

具体场景

你要给一个新环境部署配置变更，或者在线程里让 AI 改生产配置。你写一个改动，一发上去整个服务挂了，底下人在骂你。经典场景：

1. 你写一段配置改动，发上去后服务挂了

2. 你在线索里改一个 API，QA 发现它把三个其它 API 的返回值都改了

3. 你在生产做了一次环境探测，结果把健康检查的状态位打乱了

问题不在你的技术水平，在于你跳过了一步。**先做只读验证。**

什么是只读验证

**只读验证 = 在完成之前，先跑一遍目标系统的只读模式。** 意思是你不改任何东西，只检查你的改动会在哪个层面上遇到的副作用。

一次只读验证包含三个子步骤：

| 子步骤 | 你要回答的问题 | 典型操作 |

|--------|----------------|----------|

| 依赖检查 | 我的改动会触及哪些模块？哪些是只读的？ | 静态分析 / Lint / 文档搜索 |

| 影响评估 | 同层的其它代码会不会被波及？ | 线程追踪 / 流量追踪 / 日志搜索 |

| 状态确认 | 我看的数据是不是当前状态？会不会被并发修改？ | CHECKSUM / 时间戳 / 状态位对比 |

什么时候用它

- **进了新环境做第一次改动**

- **改动涉及共享资源**（API、数据库、配置）

- **你不清楚完整架构图**，只能看到其中一部分

- **有并发修改风险**（多人同时改，或者有定时任务在跑）

- **你在让 AI 或自动化系统改代码**，你没法人工审查所有改动

什么时候可以略过

- 你很清楚架构，改动范围单点明确

- 你已经做了很多次同类改动（不是第一次）

- 有现实可行的自动化回归测试兜底

- 改动不涉及共享状态（改自己的文档之类的）

怎么操作（3 步走）

步骤 1：依赖图边框检查

这一步你可能已经做过很多次写依赖梳理，但做的时候经常漏掉一类：只读判断。

**正确做法：**

1. 把要改动的所有模块列出来

2. 对每个模块，找出所有可能从那里读数据的位置

3. 对每个读位置，确认它是只读的，还是会在读的同时修改状态

4. 把非只读的位置标注出来

# 示例：改 config.yaml
-grep -r "config.yaml" --include "*.py"
# 发现：
#   main.py:5  read_config()       # 只读 → 安全
#   cache.py:12 load_config()      # 只读 → 安全
#   health.py:8 check_config()     # 读取后更新状态位 → 非只读 → 标注

步骤 2：影响面追踪

这一步最废，但也最值。你要回答：**同版本的其它代码会不会受到影响？**

**具体操作：**

1. 找出同 API 端点的所有调用方

2. 对每个调用方，确认它处理返回值的方式是否只读

3. 对涉及数据库的，找出所有读取该表的位置，确认它们是否会在读取同时做写操作

4. 对涉及共享状态的，找出所有读取该状态的位置，确认是否有并发修改

**检查表：**

- [ ] 哪些 API 端点从这个模块返回数据？

- [ ] 哪些代码直接读这个表的字段？

- [ ] 哪些模块共享这个状态位/缓存键？

- [ ] 是否有定时任务或 webhook 会修改我触及的状态？

步骤 3：状态确认（CHECKSUM 对比）

这一步是为了确认你现在看到的数据不是已经被别人改掉了。

**具体操作：**

1. 在你开始检查之前，先给关键数据打指纹

2. 检查过程中，如果遇到非只读操作，停下来，重新打指纹

3. 最终，对比指纹，确认数据没有被中间步骤篡改

# 方式一：直接文件指纹
md5sum config.yaml > /tmp/config-before.md5
# ... 你的检查和抖动 ...
md5sum config.yaml > /tmp/config-after.md5
diff /tmp/config-before.md5 /tmp/config-after.md5

# 方式二：时间戳对比
stat -c "%Y %n" config.yaml  # Linux
stat -f "%m %N" config.yaml  # macOS

常见坑

1. **只做静态检查，不做动态追踪** — 静态分析只能看到代码里写了什么，看不到运行时实际会触发什么

2. **漏掉异步/webhook/定时任务** — 这些不在主调用链上，你最容易漏掉

3. **指纹打的时间点不对** — 你在检查的过程中打指纹，但看上去是检查完了之后的数据，实际上你漏掉了中间那次修改

4. **把只读和"不改文件"混为一谈** — 读取可能修改 cache、health bit、session 状态，这不是"改动文件"，但确实是非只读操作

5. **用只读验证代替回归测试** — 只读验证确认你的检查时机对，但不能确认你的改动正确。两者都不能省

最小可用检查表

**开始检查之前：**

- [ ] 列出所有我要触达的模块

- [ ] 对每个读位置判断只读/非只读

- [ ] 找出同分的上游调用者

- [ ] 确认是否有定时任务/webhook 触及我关注的数据

- [ ] 打数据指纹

**检查过程中：**

- [ ] 每次发现非只读操作就停下

- [ ] 重新打指纹，确认时间线

**检查完成后：**

- [ ] 指纹对回来一致

- [ ] 已标注所有非只读位置

- [ ] 你的判断和你看到的架构一致，没有遗漏

检查后与开发流程关系

只读验证是开发规化前的第一道门。它不告诉你你的改动对不对，它只告诉你**你的认知和你的目标系统是否一致**。

这就是为什么它很重要：在 AI 写字的范式里，你对架构的了解能从「你记得多少」变成「你查到了多少」。只读验证就是「你查到了多少」的检查表。