本地校验通过了，为什么线上还是失败？从「校验文件」到「自检实际发出的请求体」

约 6 分钟 · 3210 字 · 11 views
本地校验通过了，为什么线上还是失败？从「校验文件」到「自检实际发出的请求体」

本地校验通过了，为什么线上还是失败？从「校验文件」到「自检实际发出的请求体」

导读：本文分析一个「本地校验全部通过、线上最后一步保存失败」的接口问题：根因不是后端，而是发送给保存接口的 config 参数被传成了 Python 字典对象（单引号、None、True/False）而非 JSON 字符串，表单编码后服务端解析失败并返回兜底错误。核心洞见是「本地文件正确 ≠ 实际发送体正确」，校验对象错位让校验再严格也拦不住；修法是新增「提交前 wire 自检」——在接受校验之后、真正发出之前校验实际请求体，并在工具层做序列化加固与请求原文回显。适合排查 LLM 工具调用参数序列化、接口契约与兜底文案类问题的工程师阅读。

分类：接口测试 ｜ 标签：接口测试、LLM、工具调用、请求体校验

一句话结论

员工上传体检报告并确认后，流程前五步全部走通——取模板 → 生成参数 → 本地校验 → 传附件——唯独最后一步「体检报告保存接口」提交失败，后端返回「保存数据失败」。根因不是后端数据问题，而是发送给接口的 config 参数被传成了 Python 字典对象（单引号 + None + True/False），而不是 JSON 字符串；表单编码后，服务端解析失败。

修法：给技能包加一个「提交前 wire 自检」环节，让"实际发出的请求体"在接受校验之后、发出之前，变成可检查的工件。

这个思路不止救这一个场景，它几乎是所有「本地校验通过、线上却失败」问题的通用答案。

一、现象：一条只有最后一步失败的链路

某次线上任务，一位员工确认上传一份体检报告（示意：7 页 PDF）。整个任务耗时约 9 分钟，除了最后一步，前面的每一步都按契约走通了：

步骤 结果
取实时模板（多个项目组、数十个字段） 成功
组装保存配置参数 就绪（字段全部组装，无阻塞）
本地表单校验 通过（校验值一致，示例 94b7…）
附件上传 成功
体检报告保存接口提交 失败（HTTP 200，业务码 -1，提示「保存数据失败」）

程序拿到失败后，先复查了本地生成的文件：编码正常、config 是标准 JSON——于是判断"原因待查"，按技能规则停止重试，如实告知员工：附件已传成功、保存未成功、报告尚未录入。

这是一个非常典型的"最后一步失败"链路：前面的环节越顺利，越容易让人以为问题出在后端。

二、排查过程：文件是对的，那哪里错了？

第一反应是后端数据问题：是不是这条记录本身有问题？是不是模板变了？但仔细回看整条任务的日志，有个细节很扎眼——同一次对话里，稍后出现过两次"写文件"调用报错，提示「content 应为字符串，实际传了对象」。也就是说，调用方在同一次任务里反复出现"把结构化对象当成字符串传"的倾向，只是在保存这个不可恢复的环节终于翻车了。

再看实际发出的请求体，问题一下清楚了。

三、根因：校验对象错位

实际发出的请求体长这样（字段值已做脱敏示意）：

body = {'config': {'categoryId': 212, 'examUserSex': None, 'employId': None,
        'generalComment': None, '...': None}, 'resource': '6', 'auditId': ''}

问题就出在 body.config 是一个 dict 对象，而接口契约要求它是一段 JSON 字符串。链路是这样的：

  1. 技能文档与本地校验脚本都明确要求：表单里的 config 必须是标准 JSON 字符串（双引号 / null / true / false），并明确禁止 Python 字典文本（单引号键、None、True/False）。这一条本地校验脚本也确实执行了，而且通过了。
  2. 但在真正调用保存接口时，调用方把 config 以解析后的 dict 对象直接传给了 HTTP 请求工具。
  3. 该工具对 application/x-www-form-urlencoded 请求是直接把请求体对象交给 HTTP 客户端编码的，嵌套的 dict 值会被字符串化后编码——于是 wire 上的 config 变成了单引号、None、True/False 的 Python 字典文本，而不是 JSON。
  4. 服务端按 JSON 解析失败（或字段结构无法识别），返回兜底业务错误「保存数据失败」（HTTP 200 / status=-1）。

为什么没被发现

因为校验脚本校验的是脚本生成的文件，而实际发出的是调用层自己重建的对象——两者之间存在落差：

本地文件正确 ≠ 实际发送体正确。

自查时看的恰是前者，看不到后者。这是本轮事故的核心盲区：校验对象错了，校验再严格也有盲区。

次要疑点（无法定性，列入排查）

  • 「保存数据失败」是后端兜底文案，服务端具体失败链路需用后端日志确认——当时建议用同一份 config 的 JSON 字符串形式重放一次做旁证。这条对后续定位仍然有效。

四、方法：提交前 wire 自检

思路一句话：把"实际发出的请求体"纳入强制校验，而不再只校验本地文件。

在「本地表单校验」与「真实调用保存接口」之间，新增一个不可跳过的「提交前 wire 自检」步骤：

改动 内容
自检脚本 比对「将要发送给 HTTP 工具的请求体」与「已通过本地校验的文件」；config 必须是 JSON 字符串且与文件逐字节一致，输出一致结果才放行
执行顺序 本地表单校验 → 提交前 wire 自检（不可跳过）→ 调用保存接口；不一致时按差异修正后重新自检
错误处理 「保存数据失败」的第一自查动作改为重跑 wire 自检：请求体与文件不一致 = 调用层序列化错误，修正后仅允许重新调用一次；一致仍失败才是服务端问题，停止重试
序列化红线 在技能文档里补充正确/错误示例（字符串 ✅ / 对象与 Python 字典文本 ❌），并强调写文件工具传 content 等"禁传对象"纪律

验证结果：自检脚本四种场景测试全部通过——请求体与文件一致 → 放行；传 dict 对象、手拼不一致、Python 字典文本 → 均拦截并给出差异。新技能包（版本号示意 v0.8，旧包已备份）通过本地静态门禁扫描。

平台层建议（收益最大的一条）

上面只是给单个技能打补丁，真正的主防线应该在工具层：

  • HTTP 请求工具序列化加固：对表单编码请求里的嵌套 dict/list 值自动序列化为 JSON，或像写文件工具一样做参数类型校验并显式报错——把"静默发出坏请求体"变成"提交前显式拦下"。
  • 可观测性：工具返回值回显实际发送的请求原文，失败时可以直接对照排查。

这两条一旦落地，就不只是护住文档 OCR 这一个技能，而是护住所有依赖表单提交的 LLM 任务。

五、延伸到 LLM 工具调用：参数纪律清单

这个案例本质上是 LLM 工具调用纪律问题。值得沉淀成清单：

  1. 模型返回的参数与代码里的对象不是一回事。 模型"认为"自己给了 JSON 字符串，实际给出的是解析后的对象或字典文本——不要相信模型的自我描述，要信真实出参。
  2. LLM 传工具参数必须显式序列化。 接口要字符串，就显式 json.dumps / JSON.stringify 后再传；禁止把原生对象（含 None/True/False）交出去。
  3. 校验要发生在 wire 上。 校验"实际发出的请求体"（抓包、记录真实出参），而不是校验本地生成的文件或内存里的对象。
  4. 失败自查有顺序。 先核对实际发送体与契约 → 再核对本地生成的文件 → 最后才怀疑服务端。兜底文案（如「保存数据失败」）不等于根因，需要服务端日志或重放旁证。
  5. 工具的入参类型校验与错误回显是主防线。 让"发坏请求体"在发出前就被显式拦下，远比事后排查便宜。

小结

一条只有最后一步失败的链路，根子却在第一步就该讲清楚的序列化问题：本地校验通过 ≠ 线上成功，因为校验对象和实际发送对象不是同一个东西。

下次再遇到"本地都对、线上失败"的接口问题，先别怀疑服务端——先问一句：你校验的，真的是你发出去的那个请求体吗？

📌 相关阅读