上游模型接口改了字段和返回结构，业务代码靠适配器层怎么保持不动？

上游模型接口改了字段或返回结构，业务代码要稳定，可行的做法是在业务与上游之间固定一层适配器，业务只依赖内部标准请求与响应模型，所有上游差异在适配器内被转换、兜底和版本化，而不是散落到各个调用点去改。这套做法适用于接了两家以上上游、或上游迭代频繁的场景；如果只接一家且几乎不迭代，适配器的维护成本可能高于收益，此时保持薄封装即可。 变更之所以让业务代码大面积崩，根因是上游的请求结构、响应结构、错误码、鉴权方式、流式协议被直接泄漏进了业务逻辑。常见链路里，业务代码里写满了某个上游专属的字段名、消息角色拼装方式和错误分支，一旦上游把 completion 改成 message、把 finish_reason 换个枚举、把超时错误码从一类改成另一类，业务层就要跟着改。把上游结构挡在业务之外，是控制爆炸半径的第一件事。 适配器吸收变更的第一层是协议转换层，负责把内部标准请求翻译成上游格式，再把上游响应翻译回内部格式。内部先定义一套与任何上游无关的请求对象，例如模型标识、消息数组、采样参数、是否流式、超时与重试策略；适配器按上游要求拼装字段。响应侧统一成固定的返回结构，包含文本内容、结束原因、用量计量、原始响应引用。这样上游换字段名、换嵌套层级、换参数位置，改动只发生在该上游对应的适配器实现里。 第二层是错误码归一化，把上游五花八门的错误映射成业务侧有限的几类可处理语义。上游的错误通常分成鉴权失败、限流、余额不足、参数不合法、内容被拦截、上游内部错误、超时与网络异常几类，但每家给的编码、文案、HTTP 状态都可能不同。适配器要做的是把这些统一映射成内部枚举，并标注该错误是否可重试、重试间隔建议、是否应降级到备用上游。业务代码只判断归一化后的类别，不判断某家上游的具体错误码字符串。 第三层是流式协议的隔离，因为流式响应是上游差异最集中的地方。有的上游按行返回数据片段，有的用特定事件类型区分增量与结束，有的在最后一个包才给用量，有的中途会插入心跳或空包。适配器应把原始流转换成内部统一的事件序列，例如增量文本事件、结束事件、用量事件、错误事件，业务侧只消费这套事件。上游调整分片方式或结束标记时，业务的处理逻辑不需要重写，只需在适配器的事件转换处同步。 统一接口的价值在于把变更点收敛到可枚举的位置，而不是消灭所有变更。判断一次上游调整是否需要动业务，可以用一条标准：这次变化是否改变了内部契约的语义。仅换字段名、换传输格式、换错误编码，属于适配器可吸收的范围；模型的输出风格、能力边界、上下文长度、计费口径发生变化，属于语义级变化，适配器只能透传信号，最终仍要业务侧决定是否调整提示词、降级策略或产品预期。把这两类变更分开对待，能避免团队在上游每次发版时都过度反应。 版本化是让适配器长期可维护的关键，做法是给内部契约定版本，而不是给上游接口定版本。适配器与内部契约版本绑定，上游出新版本时新增一个适配器实现或新增一个映射分支，旧版本继续可用，业务按自己的节奏迁移。反过来，如果内部接口跟着上游版本走，业务代码会重新耦合到上游节奏上。内部契约的版本变更应当慎用，只有当业务真正需要新语义时才升级，而不是被动跟随。 灰度与可回滚是配合适配器的第二道保险，避免一次上游调整直接打穿全量流量。常见做法是同一逻辑能力配置多个上游适配器，按比例或按租户分流，新适配器先小流量验证成功率、延迟、用量计量和流式完整性，再逐步放大；出现异常时把流量切回旧适配器或备用上游。这里的关键是业务无感，切换动作发生在路由层，业务代码不感知自己正在使用哪个上游实现。 可观测性决定了上游变更能否被及时发现，而不是等用户报错。适配器应在上游维度记录请求量、成功率、错误类别分布、首包延迟、总耗时、流式中断率，以及归一化前后的错误码对照。这样上游悄悄改了行为时，能在错误率、超时率或用量口径的异常曲线上先看到信号；同时，归一化前的原始错误码必须保留，否则排查时无法区分是上游真报了错还是适配器映射错了。 测试策略要围绕契约而不是围绕某次变更，避免适配器变成没人敢改的黑盒。建议为每个上游适配器维护一组契约测试，覆盖正常响应、参数不合法、限流、鉴权失败、流式正常结束、流式中途断开等固定场景；再配上针对内部标准模型的回归用例，验证业务拿到的仍然是同一套语义。这样上游调整时，先在测试环境跑一遍适配器契约，就能知道影响面是仅限转换逻辑还是已经触及业务语义。 配置化能减少不必要的发版，但不能替代代码层的适配。模型名称、超时、重试次数、备用上游顺序这类纯参数适合放进配置中心动态调整；字段映射、协议格式、流式解析这类逻辑不适合塞进配置，否则会变成难以测试和排查的隐式规则。合理的边界是配置管数值与启用开关，代码管结构转换与语义映射。 对多数团队而言，落地顺序可以按收益排：先把上游响应统一成内部结构并归一化错误码，收益最大；再把流式事件标准化，解决最容易被上游分片调整打破的部分；然后补路由与灰度，让多上游切换成为常态能力；最后完善可观测性与契约测试。每一步都不需要一次性重构完，但每一步都要以内部契约稳定为目标，而不是单纯把上游调用封装成一个函数。 需要说明的是，适配器不是变更免疫层，它只保证上游差异不直接冲击业务代码的调用点。当上游下架某个模型、改变计费方式、调整限流策略或收紧内容策略时，适配器能做的只是把影响转换成明确的内部信号，让业务侧有条件选择降级、切备用上游或调整产品策略。把适配器当成可以吸收一切变化，反而会在真正的语义级变更上产生误判，延误应对时机。