CCClaude Code中文喂饭教程

实战：修改接口逻辑

Claude Code 接口修改教程：接口逻辑比页面文案风险更高，要先定位调用链、输入输出、影响范围，再做最小修改和验收。

先分析，不要直接改

接口逻辑修改要先看调用链。只改返回值表面，可能会破坏调用方、测试、缓存、权限和错误处理。

/plan

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

接口：
【接口路径或方法名】

当前行为：
【现在怎么返回】

期望行为：
【希望怎么返回】

限制：
1. 先只读分析 Controller、Service、Mapper/Repository、测试和调用方。
2. 不要修改数据库结构。
3. 不要改无关接口。
4. 不要顺手重构整个服务。
5. 先给出最小修改方案和影响范围。

接口任务要确认什么

可以先让 CC 把这些信息整理成表格。表格比长段解释更容易发现缺口：

项目当前确认结果
入口路由、Controller 或 Handler
请求参数、Body、Header、鉴权信息
响应字段、错误码、状态码
调用方页面、服务、定时任务或外部系统
数据读取、写入、事务、缓存
验证已有测试、接口文档、人工调用方式

让 CC 画调用链

请只读梳理这个接口调用链，不要修改文件。

接口：
【路径或方法名】

请输出：
1. 路由或入口在哪里。
2. Controller / Handler 在哪里。
3. Service 或业务逻辑在哪里。
4. 数据读取或写入在哪里。
5. 调用方有哪些。
6. 测试或文档在哪里。
7. 修改风险是什么。

如果项目里有多个同名接口或多个服务入口，继续补一句：

请确认本次要改的是哪个真实入口。

要求：
1. 列出所有可能匹配的接口或方法。
2. 判断哪个和需求最相关。
3. 说明判断依据。
4. 不确定时不要修改文件，先向我确认。

兼容性先说清楚

接口修改最容易出问题的地方不是“新逻辑不会写”，而是旧调用方被破坏。修改前先让 CC 判断兼容性：

修改内容风险
新增响应字段通常风险较低，但要确认前端是否会误用
删除响应字段高风险，旧调用方可能直接报错
修改字段含义高风险，旧数据判断可能全部变错
修改错误码中高风险，前端提示和重试逻辑可能失效
修改鉴权规则高风险，可能影响权限和安全
修改默认排序或过滤中风险，页面结果可能变化

可复制：

请先判断本次接口修改的兼容性。

请说明：
1. 是否新增字段、删除字段或改变字段含义。
2. 是否改变状态码、错误码或错误文案。
3. 是否影响已有调用方。
4. 是否需要保留旧行为或做兼容处理。
5. 如果有高风险，请先给替代方案，不要直接改。

确认后执行

可以按最小方案修改接口逻辑。

要求：
1. 只修改和这个接口直接相关的代码。
2. 保持原有正常流程不受影响。
3. 如果有测试，请补充或运行相关测试。
4. 如果不能测试，请说明人工调用方式。
5. 完成后说明输入、输出、影响范围和剩余风险。

正常和异常都要验收

请验收接口逻辑修改。

请覆盖：
1. 正常输入。
2. 缺少必填参数。
3. 参数类型错误。
4. 权限不足。
5. 数据不存在。
6. 调用方兼容性。
7. 是否影响旧字段或旧错误码。

如果项目没有自动化接口测试，也可以让 CC 给人工调用清单，不必自己硬想：

如果当前项目没有可直接运行的接口测试，请给出人工验收清单。

要求：
1. 正常请求示例。
2. 异常请求示例。
3. 每个请求预期状态码。
4. 每个请求预期响应关键字段。
5. 需要登录或 Token 时，只说明需要什么权限，不要要求我暴露真实密钥。

验收重点

不要让 CC 顺手做这些

让 CC 解释 diff

接口改完后必须看 diff 解释，因为接口修改经常会牵出一串文件：

请解释本次接口修改的 diff。

请按文件说明：
1. 这个文件为什么必须改。
2. 改动对应需求里的哪一点。
3. 是否改变了旧接口行为。
4. 是否存在数据库、权限、缓存或日志影响。
5. 有没有文件属于顺手修改，如果有请指出。

如果接口文档也要更新

如果本次接口行为改变，请检查是否需要更新文档。

请只更新和本次接口相关的说明：
1. 请求参数。
2. 响应字段。
3. 错误码。
4. 示例。
5. 兼容性说明。

不要编造没有实现的行为。

收尾判断

接口任务最后要让 CC 给出明确结论：

请给出接口任务收尾判断。

请输出：
1. 本次接口行为变化是什么。
2. 哪些调用方确认不受影响。
3. 哪些场景已经验证。
4. 哪些场景没有验证，为什么。
5. 是否建议进入 /code-review。

验收结果

下一篇：写 README 和文档