同城朋友推理API字段升级旧客户端解析失败：我们做字段版本协商再验收
“接口还绿着，客户端却解析失败，原来返回字段升级了，旧客户端没协商版本。”
同城朋友把 EVAFAB 验收单甩过来。推理 API 返回字段升级后，旧客户端按旧结构解析失败，调用间歇报错。他试过重启客户端，还是一样。这和 TLS 主机名、并发上限一、健康检查假绿、双端口只测 HTTP、密钥缓存不是一类事，这次只盯字段版本协商、兼容层与验收。
图：Tony Webster from Minneapolis, Minnesota, United States / Wikimedia Commons / CC BY 2.0
朋友问：“是不是强制全员升级客户端？”我说先做字段版本协商，再加兼容层验收。
第一，版本协商。响应带字段版本号，客户端声明可解析版本，禁止默契假设结构不变。
第二，兼容层。旧字段保留别名映射，新字段可选；解析失败必须明确报版本不匹配。
图：Mixabest / Wikimedia Commons / Public domain
第三，对照验收。新旧客户端各跑一轮；故意下发高版本字段，旧客户端须友好失败而不是静默错读。
验收把八组调用重放。改前有五组旧客户端解析失败，改后八组都过；故意关掉兼容层，旧客户端立刻标红。朋友把规则写进同城验收说明，换人也能对表。
图：Herzi Pinki / Wikimedia Commons / CC BY-SA 4.0
字段升级看起来只是小改，不协商就会旧客户端解析失败。版本协商加兼容层再验收，比口头说接口还绿着稳。
你们同城部署推理 API 有没有遇到过字段升级后旧客户端挂掉？最后怎么固定的？欢迎讨论。
把检查写成固定步骤，比出了事再猜省力，换人值班也能按同一套标准走。
回头复盘，这类问题往往不是某一句提示词写错，而是入库、汇总、状态这些前置步骤少做了检查。
同事后来把这套步骤写进共享盘说明，新人接手也能按同样清单走一遍。
我把这次踩坑记进团队备忘，下次换环境先过一遍同样的三处改动。
验收数字摆在桌面上，比口头说好像好了更让人放心。
这类细节平时不起眼，真出了偏差排查却最费时间。
我们约定以后每次改完都留一份对照记录，方便下一次复盘。
流程写清楚之后，值班交接少了很多口头解释。
有了清单，新人也能按同样标准走完，不必每次找人问。
下次再碰到类似现象，先对清单再动手，比凭感觉改快。
值班交接时把三处改动念一遍，比事后补救省大半天。
同一套对照数字留在共享盘，下一次排查能直接对齐。
交接时把验收数字念一遍，比口头说好像好了更踏实。
我们把三处改动写进值班备忘，换班也能按同一套走。