openapi-typescript 项目中空数组查询参数导致URL异常问题解析

在 TypeScript 生态中，openapi-typescript 是一个广受欢迎的工具，它能够根据 OpenAPI/Swagger 规范自动生成 TypeScript 类型定义。其配套的 openapi-fetch 库则提供了类型安全的 API 请求功能。然而，最近发现了一个关于查询参数处理的边界情况问题，值得开发者们关注。

问题现象

当使用 openapi-fetch 发起 GET 请求时，如果传递多个空数组作为查询参数，生成的 URL 会出现异常。例如以下代码：

client.GET('/posts', {
    params: {
        query: {
            first_array: [],
            second_array: [],
            third_array: [],
            fourth_array: [],
        },
    },
});

预期行为应该是忽略这些空数组参数，就像处理 undefined 或 null 值一样。但实际生成的 URL 却是 http://localhost:3001/posts?&&&，出现了多个孤立的 & 符号。

技术分析

这种现象源于查询参数序列化逻辑中对空数组的处理不够完善。在 URL 查询字符串规范中：

1. 每个键值对通常以 key=value 形式出现
2. 多个参数用 & 符号连接
3. 空值通常应该被忽略

当前实现中，当遇到空数组时：

1. 参数名被保留
2. 由于数组为空，没有生成任何值部分
3. 但连接符 & 仍然被添加
4. 多个空数组导致多个 & 连续出现

影响范围

这种异常行为可能导致以下问题：

1. 服务器端可能无法正确解析这种非标准查询字符串
2. 可能影响缓存机制，因为 ?、?& 和 ?&& 会被视为不同 URL
3. 日志系统可能记录异常的请求 URL

解决方案建议

合理的处理方式应该遵循以下原则：

1. 空数组应该被视为"无值"，与 undefined/null 同等对待
2. 完全忽略空数组参数的序列化
3. 确保不会生成孤立的 & 符号
4. 保持与主流 HTTP 客户端库的行为一致性

修复方案可以是在参数序列化阶段增加对空数组的过滤，或者在 URL 构建完成后对连续的 & 符号进行清理。

最佳实践

在使用 openapi-fetch 时，开发者可以暂时采取以下规避措施：

1. 手动过滤掉空数组参数
2. 使用可选链操作符避免传递空数组
3. 对参数进行预处理，将空数组转换为 undefined

const cleanParams = Object.fromEntries(
    Object.entries(params.query).filter(([_, value]) => 
        !Array.isArray(value) || value.length > 0
    )
);

总结

这个边界情况提醒我们，在开发 HTTP 客户端库时需要特别注意各种参数类型的处理逻辑。特别是对于集合类型（如数组）的空值情况，应该保持与标量类型一致的处理方式。开源社区已经注意到这个问题，预计会在后续版本中修复。