模块重置后重新添加接口问题复盘

编写时间：2026-07-13；使用模型：Codex GPT-5；用户：Jsmond2016

---

问题摘要

当前模块包含 /api/user/queryOne 时，执行“重置模块”会清空列表，但随后通过添加表单重新输入该地址，可能提示“匹配到 2 个接口，请输入更完整的接口地址”，导致接口必填信息无法自动补全。

单条删除后重新添加同一接口不受影响。模块重置应与逐条删除模块内全部接口具有一致的结果。

最终修复后，用户重新执行上述操作并确认验证通过。

用户操作路径

1. Tab A 中已存在 /api/user/queryOne。
2. 点击 Tab 内的“重置模块”，清空该模块的全部接口。
3. 等待任意时长后点击“添加”。
4. 在“接口地址”中重新输入 /api/user/queryOne。
5. 输入框失焦后出现“匹配到 2 个接口，请输入更完整的接口地址”，其余必填字段未能自动补全，导致无法完成添加。

排查过程

第一阶段：误判为重置持久化竞态

最初根据“重置后重新添加”这一操作顺序，将问题归因于重置和新增均未等待 saveConfig() 完成，怀疑 chrome.storage 的回写将旧配置重新写入 Zustand，导致已删除接口继续参与本地重复校验。

进一步核对提示文案后发现，本地重复校验的提示是“该接口地址已存在，请使用不同的地址”，而用户看到的提示仅由添加表单的 Swagger 模糊匹配逻辑产生。因此，持久化竞态不是该提示的直接根因。

这一阶段仍保留了两项有效改进：

• 重置时从 Store 获取最新配置，避免确认弹窗闭包持有旧状态。
• 等待持久化完成后再提示成功，并清理被重置接口的残留勾选状态。

第二阶段：首次修正 Swagger 匹配

Swagger 匹配原先使用双向包含判断：

Swagger path 包含输入值，或输入值包含 Swagger path

初次修正增加了以下规则：

• 精确路径优先于前缀相似的模糊路径。
• 过滤 parameters 等非 HTTP 方法字段，避免将其计为接口。
• 精确路径存在多个方法时，优先当前表单方法。

新增测试全部通过，但用户复测仍然得到相同提示，说明测试数据没有覆盖真实失败分支。

第三阶段：定位遗漏分支

复查精确匹配分支后发现：同一精确 path 存在多个请求方法，且这些方法不包含表单默认的 GET 时，代码仍返回多个匹配。例如 Swagger 同时包含 POST /api/user/queryOne 和 PUT /api/user/queryOne，表单默认方法为 GET，此时依然得到 matchCount = 2。

这个提示无法通过输入“更完整的接口地址”解决，因为多个结果拥有完全相同的地址，差异仅在请求方法。

同时补查到原有规范化逻辑只移除开头的 /，没有统一处理完整 URL、查询参数和尾斜杠，这些输入也可能使本应精确匹配的地址退化为模糊匹配。

根因结论

问题的直接根因不是接口未被重置，也不是本地重复校验，而是 Swagger 匹配把“接口操作数量”错误地当成“不同接口地址数量”：

• 同一路径的多个 HTTP 方法被计为多个地址候选。
• 当前表单方法不在候选中时，即使路径完全一致也会返回多匹配。
• 提示要求输入更完整的地址，但同路径多方法场景无法通过地址消歧。
• 路径规范化不足会让部分精确地址错误进入模糊匹配分支。

“重置模块”是用户稳定触发问题的业务入口，但错误提示实际来自添加表单的 Apifox Swagger 补全流程。

最终修复

模块重置

• 确认重置时读取 Zustand 最新配置。
• 仅清空当前模块的 apiArr，不影响其他模块。
• 清理已删除接口对应的选中 ID。
• 等待 saveConfig() 完成后提示重置成功。

Swagger 匹配

• 复用 normalizeApiLookupPath()，统一处理相对路径、完整 URL、查询参数、重复斜杠和尾斜杠。
• 仅将 GET、POST、PUT、DELETE、PATCH 计为有效接口操作。
• 只要存在精确路径，就不再进入模糊多匹配提示。
• 精确路径存在多个方法时优先当前表单方法；当前方法不存在时使用 Swagger 中首个有效方法，并将该方法回填表单。
• 只有不存在精确路径且模糊候选超过一个时，才提示用户输入更完整的地址。

验收标准

• [x] 重置仅清空当前模块，不修改其他模块。
• [x] 重置使用最新配置并在持久化完成后提示成功。
• [x] 重置时清理该模块接口对应的勾选状态。
• [x] 重置后，本地重复校验不再命中已清空的接口地址。
• [x] 添加表单优先匹配 Swagger 中的精确路径和当前请求方法。
• [x] 精确路径存在多个方法且当前方法不存在时，仍能选择有效方法并完成字段补全。
• [x] 完整 URL、查询参数和尾斜杠按统一路径规则规范化后匹配。
• [x] OpenAPI path 下的 parameters 等非 HTTP 方法字段不计入接口数量。
• [x] 不存在精确匹配时，保留原有多条模糊匹配提示。
• [x] 用户按原始操作路径复测通过。

回归测试

场景	预期结果
重置模块后检查原接口地址	不再命中本地重复校验
重置模块 A	模块 B 的接口保持不变
精确路径与相似前缀路径同时存在	选择精确路径
path 下包含 parameters	只统计有效 HTTP 方法
精确路径包含当前表单方法	选择当前方法
精确路径不包含默认 GET	选择首个有效方法，不提示地址不完整
输入完整 URL、查询参数和尾斜杠	规范化后命中精确路径
只有多个模糊路径	保留多匹配提示

全量 Vitest 测试结果为 14/14 通过，定向 ESLint 通过，Chrome 生产构建通过。全量 TypeScript 检查仍有 2 个既有错误，分别位于 ArchiveListModal.tsx 和 SyncApifoxModal.tsx，与本次修改无关。

复盘结论

• 提示文案是定位数据流的重要证据。应先搜索提示来源，再判断问题属于本地状态、持久化还是外部数据解析。
• 回归测试不能只覆盖理想化的单方法 Swagger；同路径多方法、非方法字段和 URL 规范化均属于 OpenAPI 解析的必要边界。
• “操作入口”和“直接根因”可能位于不同模块。重置触发了问题，但错误发生在后续添加表单的 Swagger 补全流程。
• 多匹配提示必须提供可执行的消歧方式。同路径多方法不能通过补充地址解决，应由请求方法消歧或采用确定性回退。

任务状态

任务	状态	关联实现
修正模块重置状态提交与持久化	已完成	ResetModuleButton.tsx、resetModuleUtils.ts
修正添加表单 Swagger 匹配	已完成	ApiFormDrawer.tsx、apiFormUtils.ts
添加回归测试	已完成	apiFormUtils.test.ts、resetModuleUtils.test.ts