openapi-typescript 0.10.0 版本升级中的 fetch 请求问题解析

在升级 openapi-typescript 到 0.10.0 版本时，开发者可能会遇到一个特定的错误："Failed to execute 'fetch' on 'Window': The duplex member must be specified for a request with a streaming body"。这个问题主要出现在浏览器环境中，特别是使用 Chromium 内核的浏览器（如 Chrome 和 Edge），而在 Firefox 中却能正常工作。

问题根源

这个问题的本质在于 openapi-fetch 库在 0.10.0 版本中对 fetch 请求的处理方式发生了变化。新版本中，库会将 Request 对象实例直接传递给 fetch 方法作为第二个参数，而不是传递一个普通的配置对象。

根据 Fetch API 规范，当使用 Request 对象作为 fetch 的第二个参数时，如果请求体是可读流（streaming body），Chrome 会严格要求必须指定 duplex 参数。这是 Chrome 特有的实现行为，Safari 会有不同的相关错误，而 Firefox 则能自动处理这种情况。

技术背景

duplex 是 Fetch API 的一个相对较新的属性，用于指示请求是半双工还是全双工通信。在流式传输请求体时，明确指定这个参数有助于浏览器优化网络处理。

在 openapi-fetch 0.10.0 版本中，这个变化原本是为了更好地支持第三方自定义 fetch 实现，但无意中引入了对 Chrome 的兼容性问题。

解决方案

目前有两种临时解决方案：

1. 手动为请求添加 duplex 属性：

// 在中间件中修改请求
onRequest: ({ request }) => {
  request.duplex = 'half';  // 明确指定半双工模式
  return request;
}

2. 回退到 0.9.0 版本，等待官方修复。

最佳实践建议

对于使用 openapi-typescript/openapi-fetch 的开发者，建议：

1. 在升级到 0.10.0 版本前，充分测试所有 API 请求
2. 特别注意浏览器环境中的 POST 请求
3. 考虑为所有流式请求显式设置 duplex 参数
4. 关注官方更新，及时应用修复版本

总结

这个案例很好地展示了前端开发中浏览器兼容性问题的重要性。即使是遵循规范的变更，也可能因为不同浏览器引擎的实现差异而导致问题。作为开发者，我们需要：

1. 理解底层 API 规范
2. 了解不同浏览器的实现差异
3. 建立完善的跨浏览器测试机制
4. 谨慎对待依赖库的版本升级

openapi-typescript 团队已经确认这个问题，并计划在后续版本中修复，同时会增强测试覆盖以避免类似情况再次发生。