OpenAPI-TS 项目中 URLSearchParams 序列化问题的深度解析

问题背景

在 React Native 开发环境中使用 OpenAPI-TS 自动生成的 SDK 时，开发者遇到了一个关于表单数据序列化的典型问题。当调用 OAuth 认证接口时，虽然代码正确设置了 application/x-www-form-urlencoded 内容类型，但请求体却未被正确序列化，导致服务器返回 422 错误。

问题本质

经过深入分析，这个问题并非如最初猜测的与 Hermes 引擎缺少 URLSearchParams 支持有关，而是源于 fetch 客户端在处理 URLSearchParams 对象时的实现差异。

核心发现是：在 React Native 环境中，直接将 URLSearchParams 对象作为 fetch 请求的 body 时，其内容不会被自动序列化为字符串。这与 Node.js 和浏览器环境的行为不同，后者会自动处理这种转换。

技术细节

在标准环境中，以下两种写法是等价的：

// 写法一：直接传递 URLSearchParams 对象
new Request(url, { body: new URLSearchParams(params) })

// 写法二：显式转换为字符串
new Request(url, { body: new URLSearchParams(params).toString() })

但在 React Native 中，只有第二种写法能正确工作。第一种写法虽然看似设置了 body，但实际上请求体内容为空。

解决方案

正确的处理方式应该是：

1. 在使用 URLSearchParams 序列化请求体时，显式调用 toString() 方法
2. 确保内容类型头正确设置为 application/x-www-form-urlencoded

OpenAPI-TS 项目已通过 PR 修复了这个问题，修改了 fetch 客户端的实现，确保在所有环境中都能正确序列化表单数据。

开发者启示

1. 环境差异意识：跨平台开发时，必须考虑不同 JavaScript 运行时的行为差异
2. 显式优于隐式：对于数据序列化等关键操作，显式转换比依赖环境行为更可靠
3. 测试覆盖：重要功能应在目标环境中进行充分测试，不能仅依赖开发环境的验证

最佳实践建议

对于使用 OpenAPI-TS 的 React Native 开发者：

• 更新到包含此修复的最新版本
• 对于关键 API 调用，建议添加单元测试验证请求体格式
• 考虑在应用初始化时添加环境检测和必要的 polyfill

这个问题也提醒我们，在现代 JavaScript 开发中，理解底层 API 的行为差异对于构建健壮的跨平台应用至关重要。