OpenAPI-TS 项目中数组查询参数序列化问题解析

在 OpenAPI-TS 项目中，开发者在使用 OpenAPI 3.0 规范定义查询参数时，可能会遇到数组类型参数的序列化问题。本文将深入分析这一问题及其解决方案。

问题现象

当在 OpenAPI 规范中定义数组类型的查询参数时，开发者期望参数能够按照特定格式序列化，但实际生成的客户端代码却产生了不同的结果。具体表现为：

1. 当设置 explode: false 时，期望生成 ?example=e1,e2 格式，但实际生成了 ?example=e1&example=e2
2. 未明确设置 explode 属性时，参数名会意外添加 [] 后缀，如 ExamStates[]=3&ExamStates[]=4

问题根源

这个问题的核心在于 OpenAPI-TS 项目中对 OpenAPI 规范中查询参数序列化规则的处理不够完善。OpenAPI 3.0 规范定义了四种参数序列化方式：

1. form - 默认方式
2. spaceDelimited
3. pipeDelimited
4. deepObject

其中 explode 属性控制着数组元素的展开方式。当 explode 为 false 时，数组元素应该用逗号连接；为 true 时，则应该展开为多个同名参数。

解决方案

目前 OpenAPI-TS 项目提供了几种解决方式：

1. 使用实验性解析器：在配置中设置 experimentalParser: true，新版本的解析器已经修复了这个问题。

2. 自定义参数序列化器：可以通过配置 paramsSerializer 来覆盖默认的序列化行为：

   const client = createClient({
     paramsSerializer: {
       serialize: (params) => {
         // 自定义序列化逻辑
       }
     }
   });
   

3. 使用查询序列化器：对于特定请求，可以传递 querySerializer 参数来覆盖全局设置。

最佳实践建议

1. 在 OpenAPI 规范中明确指定 explode 属性，避免依赖默认行为
2. 对于数组参数，考虑使用 style 和 explode 组合来精确控制序列化格式
3. 升级到最新版本的 OpenAPI-TS，并使用实验性解析器以获得最佳兼容性
4. 对于关键接口，建议编写测试用例验证参数序列化结果

总结

OpenAPI-TS 项目正在不断完善对 OpenAPI 规范的支持。理解参数序列化规则对于构建符合预期的 API 客户端至关重要。开发者应当根据实际需求选择合适的解决方案，并在项目升级时关注相关改进。