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

问题背景

在OpenAPI-Typescript项目的openapi-fetch组件中，存在一个关于对象类型查询参数序列化的行为差异问题。根据OpenAPI 3.0规范，当对象作为查询参数时，默认应采用"form"样式序列化并启用explode模式。然而当前实现却使用了"deepObject"样式，导致生成的URL参数格式与规范预期不符。

技术细节分析

在OpenAPI规范中，查询参数的序列化有以下几种方式：

1. form样式+explode：默认方式，将对象属性展开为独立的键值对

   • 示例：role=admin&firstName=Alex

2. deepObject样式：使用方括号表示嵌套结构

   • 示例：id[role]=admin&id[firstName]=Alex

3. 其他组合：form样式不展开、pipe分隔等

当前openapi-fetch实现默认使用了deepObject样式，这与规范定义的标准行为存在差异。这种差异可能导致与某些后端API的兼容性问题，特别是那些严格按照OpenAPI规范实现的服务器。

解决方案探讨

短期解决方案

对于需要立即解决问题的开发者，可以自定义查询参数序列化器。以下是一个实现form+explode样式的示例：

const serializePrimitive = (key, value) => `${key}=${encodeURIComponent(String(value))}`;

const serializeArray = (key, value, serializer) => {
  if (!value.length) return undefined;
  return value
    .map((item) => serializer(key, item))
    .filter(Boolean)
    .join('&');
};

const serializeObject = (value, serializer) => {
  const entries = Object.entries(value).filter(([_, v]) => v !== undefined && v !== null);
  if (!entries.length) return undefined;
  return entries
    .map(([k, v]) => serializer(k, v))
    .filter(Boolean)
    .join('&');
};

export const querySerializer = (q) => {
  const search: string[] = [];
  if (q && typeof q === 'object') {
    for (const [k, v] of Object.entries(q)) {
      const value = queryParamSerializer(k, v);
      if (value) {
        search.push(value);
      }
    }
  }
  return search.join('&');
};

长期改进方向

项目维护者提出了几个有价值的改进思路：

1. 分离对象和数组的序列化逻辑：这将提供更细粒度的控制，允许开发者分别定制不同数据类型的序列化方式

2. 增强路径参数序列化支持：当前对路径参数的序列化支持不够完善，计划在后续版本中改进

3. 提供内置序列化器集合：考虑提供多种常见序列化样式（如formExplode）作为内置选项，方便开发者选择

版本规划

这些改进将被纳入即将发布的0.9.0版本中，该版本将包含一些必要的破坏性变更，以更好地支持OpenAPI规范的各种序列化需求。

开发者建议

对于当前面临此问题的开发者，建议：

1. 如果后端严格遵循OpenAPI规范，使用自定义序列化器临时解决问题
2. 关注0.9.0版本的发布，评估是否需要升级
3. 对于新项目，明确前后端对参数序列化的约定，确保一致性

这个问题的讨论展现了开源社区如何协作解决技术规范与实际实现间的差异，同时也体现了项目维护者对向后兼容性和规范遵从性的平衡考虑。