AI Agent / 系统课时

安全重构代码

安全重构代码

安全重构的目标是改变内部结构而不改变外部行为。使用 Codex 时,重点不是让它“大胆整理代码”,而是先明确哪些行为必须冻结、允许改哪些文件,再用测试、静态检查和差异审查证明结构变了而契约没变。

学习目标

  • 区分允许变化的内部实现与必须保持不变的外部契约
  • 为 Codex 写出带范围、禁止项和验证命令的重构任务
  • 通过基线测试、差异审查和回归验证控制重构风险

先冻结外部行为

开始重构前先定义不可变化的契约,例如公开函数名与参数、返回值、异常类型、序列化格式、数据库副作用或接口状态码。现有测试就是最直接的行为护栏;如果关键契约没有测试,应先补测试,再动内部结构。

重构前先取得一份干净基线。下面假定当前仓库使用 Python 标准库测试。

bash
git status --short
python -m unittest -q

预期输出:

text
----------------------------------------------------------------------
Ran <VALUE> tests in <TIME>s

OK

git status --short 在干净工作区中不输出内容;<VALUE> 和 <TIME> 取决于当前项目。基线如果已经失败,就不能把重构后的失败简单归因于本次改动,应先记录或消除原有故障。

安全重构中的行为边界与验证闸门

给 Codex 的任务必须写清边界

高风险提示词通常只有一句“重构这个模块”,它没有说明什么不能变,也没有验收标准。更稳妥的做法是把目标、范围、禁止项和验证命令一次写清,并让 Codex 先阅读相关代码和测试再修改。

bash
codex exec '重构 src/parser.py,目标是消除重复的字段规范化逻辑并改善命名。保持所有公开函数签名、返回值、异常类型和现有输入兼容性不变;不要修改测试来迁就实现,也不要改动 src/parser.py 和直接相关测试之外的文件。先阅读现有测试确认行为契约,再实施最小结构调整,最后运行 python -m unittest -q,并说明你修改了什么以及为什么外部行为保持不变。'

预期输出:

text
<VALUE>

<VALUE> 是 Codex 针对当前仓库给出的执行摘要,内容会随代码而变化。真正的完成条件是它遵守文件范围和行为约束,并且验证命令通过,而不是摘要中出现“refactor complete”之类表述。

用差异判断它是在重构还是改行为

测试通过只能说明已有测试覆盖的行为没有明显退化,不能替代差异审查。重构后的 git diff 应主要呈现命名整理、重复逻辑合并、函数拆分或模块移动;如果出现业务常量变化、错误分支删除、默认值调整、接口字段变化,就已经越过了“仅重构”的边界。

bash
git diff --check
git diff --stat
git diff
python -m unittest -q

预期输出:

text
<VALUE>

----------------------------------------------------------------------
Ran <VALUE> tests in <TIME>s

OK

第一个 <VALUE> 代表项目实际的差异统计和补丁内容。git diff --check 正常时通常没有输出。审查时尤其关注“删除的条件判断”和“修改的断言”:它们最容易把行为变化伪装成代码清理。

大重构要拆成可回退的小步

跨模块重构不要一次同时做重命名、移动文件、抽象接口和改变数据结构。更安全的顺序是先做纯机械变化并验证,再处理去重或抽象,每一步都保持测试可运行、差异可解释。这样 Codex 某一步越界时,可以只回退该步,而不是重新审查一个巨大补丁。

如果仓库已有项目级开发说明、测试脚本或代码规范,应把它们作为约束来源,而不是在提示词中重新发明一套规则。最终验收标准很简单:外部契约没有变化,所有既有验证仍然通过,新增结构确实降低了重复或复杂度,而且差异中没有与目标无关的“顺手修改”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

安全重构代码

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通