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

具体场景

你要给一个新环境部署配置变更，或者在线程里让 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 写字的范式里，你对架构的了解能从「你记得多少」变成「你查到了多少」。只读验证就是「你查到了多少」的检查表。