Kysely 0.27 版本中 SQL RawBuilder 类型错误解析

Kysely 是一个类型安全的 SQL 查询构建器，在 0.27 版本更新后，开发者在使用 sql RawBuilder 构建 where 条件时可能会遇到类型错误。本文将详细解析这个问题及其解决方案。

问题现象

在 Kysely 0.27 版本中，当开发者尝试使用 sql 标签模板构建 where 条件时，可能会遇到如下类型错误：

Argument of type 'RawBuilder<unknown>' is not assignable to parameter 
of type 'ExpressionOrFactory<DB, "myTableName", SqlBool>'

这种情况常见于以下场景：

1. 使用 PostgreSQL 的全文搜索功能（tsquery）
2. 使用 BETWEEN 等复杂条件表达式

问题原因

Kysely 0.27 版本对类型系统进行了强化，要求 where 子句中的表达式必须明确返回布尔类型。而 sql 标签模板默认返回的是 unknown 类型，这会导致类型不匹配的错误。

解决方案

正确的做法是为 sql 标签模板显式指定返回类型为 boolean：

where(sql<boolean>`search_terms @@ to_tsquery('simple', ${searchText})`)

或者对于 BETWEEN 表达式：

where(sql<boolean>`column BETWEEN ${start} AND ${end}`)

最佳实践

1. 明确类型：始终为 where 子句中的 sql 表达式指定 boolean 类型参数
2. 代码可读性：对于复杂的 SQL 片段，可以考虑提取为单独的函数或变量
3. 类型检查：利用 TypeScript 的类型系统确保 SQL 表达式的正确性

总结

Kysely 0.27 版本的这一变化实际上是类型系统强化的表现，虽然增加了少量的样板代码，但带来了更好的类型安全性。开发者应该适应这一变化，在编写 where 条件时显式指定返回类型，以避免类型错误并提高代码质量。

对于从旧版本迁移的项目，建议全局搜索 where(sql 并添加适当的类型参数，这是保证类型安全性的必要步骤。