后端不符合约定时
这一页说明后端的格式或能力和后端约定不一样时怎么办。
结论
- 适配器不提供兼容不规范后端的开关。
- 差异有三种处理办法:在能力函数里转换;加自己的服务层;不给这项能力。
- 数据都有、只是格式不同,用第一种。缺数据、要存东西才能补上,用第二种。补不了或不值得补,用第三种。
选哪一种
做法一:在函数里转换
history、sessions 等单次能力返回 Response。格式不同时可读出、转换后再包装;流式能力也可返回异步事件序列,不能先把整条流当普通 JSON 读完。
下面的后端有历史接口,但字段名不一样:
adapter.ts
后端用 200 表示失败、响应外面多包了一层时,同样在函数里处理:
adapter.ts
做法二:加自己的服务层
后端缺数据时,在浏览器和后端之间加一层自己的服务。请求经过它,它来补后端没有的东西:
下面是其中一件事的例子,给上游的流加事件编号。这段代码运行在服务端:
with-event-ids.ts
服务层同时也是生产环境要有的那一层代理:密钥留在这里,用户是谁由这里根据登录态决定。
做法三:不给这项能力
后端做不到、服务层也不值得补的能力,不给对应的函数。能力相关入口按配置隐藏或禁用;未提供 abort 时不能停止已派发的轮次。
adapter.ts
以后后端支持了,加上对应的函数就行,别的代码不用动。
为什么不提供兼容的开关
SDK 的数据约定不是所有后端的官方协议。可长期使用经过验证的转换或代理,无需为了字段名差异改动后端协议。
示例的适用范围
历史转换示例仅映射消息,没有补造 runs;它不能恢复未提供的执行结论。unwrap 示例只处理普通 JSON 接口,不能用于 SSE。
withEventIds 只演示以 LF 空行分帧后添加编号,没有覆盖 CRLF、已有 id、尾部残帧、异步持久化和跨连接编号连续性。它不是完整重放服务;编号、已应用历史前缀和事件持久化需要一起设计。
省略能力时,断线不会显示为失败:未收到协议结论时结果未知,也不会自动重发。