Fumadocs项目中OpenAPI Playground组件searchParams参数处理问题解析

在Fumadocs项目的OpenAPI Playground组件中发现了一个关于URL参数处理的典型问题。当用户清空查询参数时，组件未能正确清理URL中的空字符串参数，导致API调用失败。

问题现象

在OpenAPI Playground组件中，当用户执行以下操作时会出现异常：

1. 正常填写查询参数并成功获取200响应
2. 清空所有查询参数值
3. 组件仍保留空字符串参数在URL中
4. 最终导致API返回400错误

技术分析

这个问题本质上是URL参数状态管理的问题。在Web开发中，当表单输入被清空时，理想情况下应该：

1. 完全移除对应的查询参数
2. 或者将其设置为undefined/null
3. 而不是保留空字符串值

当前实现保留了空字符串参数，这违反了REST API的最佳实践。大多数API服务器会将空字符串视为有效值，而不是忽略该参数。

解决方案

正确的处理方式应该包括：

1. 在参数值为空时完全移除该参数
2. 更新URL时过滤掉空值参数
3. 确保状态同步更新

实现建议

在React组件中，可以通过以下方式改进：

// 过滤掉空值参数
const cleanParams = Object.fromEntries(
  Object.entries(params).filter(([_, value]) => value !== '')
);

// 更新URL时使用清理后的参数
updateURL(cleanParams);

额外优化建议

1. URL同步显示：建议让代码片段中的URL也实时反映参数变化，提升开发者体验
2. 参数验证：可以增加前端参数验证，提前拦截无效请求
3. 错误处理：提供更友好的错误提示，帮助开发者理解问题原因

这个问题虽然看似简单，但反映了前端状态管理和API交互中的常见陷阱，值得开发者注意。