ts-rest项目中布尔查询参数解析问题分析

问题背景

在ts-rest项目从3.30.1版本升级到3.41.2版本后，开发者发现了一个关于布尔类型查询参数的有趣现象。当定义一个包含布尔查询参数的API端点时，无论客户端传递的是true还是false，服务器端接收到的值总是被解析为true。

问题复现

开发者定义的API契约如下：

method: 'GET',
path: "get-something",     
query: z.object({
    show: z.coerce.boolean(),
}),
responses: {
    200: c.type<any>()
}

当客户端传递show=false时，服务器端通过r.query.show获取的值却始终为true，这与预期行为不符。

技术分析

底层机制

1. HTTP查询参数本质：HTTP协议中，查询参数总是以字符串形式传输，没有原生布尔类型的概念。

2. 类型转换行为：

   • Boolean('false')在JavaScript中会返回true，因为任何非空字符串都会被转换为true
   • 这是JavaScript的隐式类型转换规则决定的

3. 版本差异原因：

   • 旧版本(3.30.1)可能使用了不同的解析策略
   • 新版本(3.41.2)更严格遵循了HTTP协议规范

解决方案

1. 使用字符串类型：最直接的解决方案是将参数定义为字符串类型，然后在业务逻辑中手动转换

   query: z.object({
       show: z.string().transform(val => val === 'true'),
   })
   

2. 启用jsonQuery：ts-rest提供了jsonQuery选项，可以支持更复杂的数据类型

   new ApiBuilder().setConfig({ jsonQuery: true }).build()
   

3. 自定义解析器：可以创建自定义的解析逻辑来处理布尔值转换

最佳实践建议

1. API设计原则：在设计RESTful API时，查询参数最好保持为简单类型(字符串、数字)

2. 类型安全：对于需要复杂类型的场景，考虑使用请求体(POST/PUT)而非查询参数

3. 版本兼容性：升级库版本时，应该仔细检查类型系统的变更

4. 文档说明：在API文档中明确标注参数类型和预期的格式

总结

这个问题揭示了HTTP协议与类型系统之间的微妙关系。虽然表面上看起来像是一个bug，但实际上反映了类型系统在Web环境中的固有挑战。开发者需要理解底层机制，选择最适合自己应用场景的解决方案。