常见任务实战：让 Codex 修改一段接口逻辑

修改接口逻辑比改页面更进一步，但还不算高阶。

前置教程：常见任务实战：让 Codex 补 README 或使用说明
如果你还没有练习过让 Codex 基于项目真实结构写文档，先完成前置教程。

依据来源：OpenAI Codex 官方手册中的项目阅读、任务边界、验证、diff 审查和安全建议。

这个案例适合谁

适合这些任务：

修改一个查询条件。
增加一个返回字段。
调整一个参数校验。
修改一个错误提示。
给一个接口增加简单日志。

不适合：

改数据库表结构。
重构整个服务层。
修改认证权限体系。
同时改多个接口。
影响支付、订单、资金、权限等高风险逻辑。

第一次修改接口，只选低风险小逻辑。

第 1 步：让 Codex 先理解接口

不要直接说：

帮我改一下用户接口。

先只读分析：

请先只读分析当前项目，不要修改任何文件。

我准备修改一个接口逻辑。请告诉我：
1. 当前项目的后端入口在哪里。
2. 接口路由或 Controller 在哪里。
3. Service 或业务逻辑文件在哪里。
4. 当前接口有没有测试。
5. 修改接口前需要确认哪些风险。

如果是前端项目调用后端接口，也可以问：

请只读分析当前前端项目，不要修改文件。
请找出【接口名称或请求路径】在哪里被调用，以及返回结果影响哪些页面。

第 2 步：写清楚接口变更需求

接口任务必须写清楚：

改哪个接口。
当前行为是什么。
期望行为是什么。
输入输出怎么变。
哪些情况不能影响。

模板：

请帮我修改一个接口逻辑。

接口：
【接口路径或函数名】

当前行为：
【现在怎么处理】

期望行为：
【希望改成什么】

限制：
1. 只修改这个接口直接相关的最小代码。
2. 不要修改数据库结构。
3. 不要修改认证权限逻辑。
4. 不要影响其他接口。
5. 修改前先说明计划。

验收标准：
1. 正常请求返回符合预期。
2. 异常输入有明确处理。
3. 原有不相关接口不受影响。
4. 如果有测试，请说明运行结果；如果没有测试，请给出人工验证方式。

第 3 步：让 Codex 先给影响范围

接口逻辑容易牵连。

修改前问：

先不要修改文件。
请先说明这次接口修改可能影响哪些文件、哪些调用方、哪些测试。
请给出最小修改方案。

你要看：

是否只影响一个接口。
是否需要改前端调用。
是否需要改类型定义。
是否需要改测试。
是否涉及权限、数据库、缓存。

如果涉及高风险：

这次先不要做高风险改动。
请把任务缩小到不改数据库、不改权限、不改缓存的最小逻辑修改。

第 4 步：批准修改

计划清楚后：

可以按最小修改方案处理。
请只修改和这个接口直接相关的文件。
完成后请总结 diff、验证方式和剩余风险。

第 5 步：让 Codex 验证

接口修改后，要看它怎么验证。

提示词：

请根据当前项目情况验证这个接口修改。

要求：
1. 如果项目有相关测试，请说明是否运行以及结果。
2. 如果没有测试，请给出手动验证步骤。
3. 请列出正常输入、异常输入和边界输入。
4. 请判断是否影响其他接口。

你不需要自己凭空想测试点，让 Codex 先列。

你负责判断它列得是否合理。

第 6 步：检查 diff 和风险

接口改动必须看风险。

请检查本次接口修改的风险。

要求：
1. 列出修改文件。
2. 说明每个文件为什么必须修改。
3. 判断是否影响认证、权限、数据库、缓存、其他接口。
4. 判断是否需要补测试。
5. 给出是否可以提交前检查的结论。

如果 Codex 说“可能影响其他接口”，先不要提交。

让它继续缩小或补验证。

第 7 步：生成交付总结

请给出本次接口修改总结：
1. 原始需求。
2. 修改方案。
3. 修改文件。
4. 验证结果。
5. 剩余风险。
6. 建议提交说明。

本案例验收

完成后，你应该得到：

接口相关文件定位。
最小修改方案。
修改后的 diff 总结。
正常、异常、边界验证方式。
风险说明。
提交前检查结论。

下一步可以进入真正高阶内容：全站内容规划。