Kysely 项目中实现可复用 WHERE 条件的类型安全方案

问题背景

在使用 Kysely 这个类型安全的 SQL 查询构建器时，开发者经常会遇到需要复用 WHERE 条件的场景。例如，多个查询可能都需要根据名称进行模糊搜索，但每个查询可能涉及不同的表组合。

初始尝试与问题

开发者最初尝试创建一个通用的 WHERE 条件函数，接受一个 SelectQueryBuilder 作为参数。基本思路是：

function getParticipantVariablesWhere<O>(
  query: SelectQueryBuilder<DB, "Variables" | "ParticipantVariables", O>,
  params: GetParticipantVariables
) {
  if (params.searchName) {
    query = query.where("Variables.name", "ilike", `%${params.searchName}%`);
  }
  return query;
}

这种方法的问题在于它限制了查询必须只包含"Variables"和"ParticipantVariables"两个表，而实际使用中查询可能包含更多表。

改进方案

方案一：联合类型（不推荐）

尝试使用联合类型来扩展可能的表组合：

function getParticipantVariablesWhere<O>(
  query: 
    | SelectQueryBuilder<DB, "Variables" | "ParticipantVariables", O>
    | SelectQueryBuilder<DB, "Variables" | "ParticipantVariables" | "VariableValues", O>,
  params: GetParticipantVariables
) {
  // ...
}

这种方法会导致类型系统无法正确推断 where 方法的签名，产生类型错误。

方案二：泛型扩展（部分可行）

尝试使用泛型参数来扩展表集合：

function getParticipantVariablesWhere<O, TB extends keyof DB>(
  query: SelectQueryBuilder<DB, "Variables" | "ParticipantVariables" | TB, O>,
  params: GetParticipantVariables
) {
  // ...
}

这种方法的问题是 TypeScript 无法保证"Variables.name"在扩展后的表集合中仍然有效。

推荐解决方案

经过社区讨论，推荐使用以下模式：

1. 创建一个基础查询构建器
2. 通过方法链式调用添加条件
3. 使用类型断言确保表存在

示例实现：

function withNameCondition<TB extends keyof DB & ("Variables" | "ParticipantVariables")>(
  query: SelectQueryBuilder<DB, TB, any>,
  searchName?: string
) {
  if (searchName) {
    return query.where("Variables.name", "ilike", `%${searchName}%`) as SelectQueryBuilder<DB, TB, any>;
  }
  return query;
}

这种方法通过类型约束确保查询至少包含必要的表，同时保持灵活性。

最佳实践

1. 最小表集合约束：在函数签名中只约束必要的表
2. 类型安全：确保 WHERE 条件引用的列在所约束的表集合中存在
3. 可组合性：设计条件函数可以链式组合使用
4. 明确文档：为每个条件函数明确说明其表依赖关系

总结

在 Kysely 中实现可复用的 WHERE 条件需要平衡类型安全性和灵活性。通过合理的类型约束和方法设计，可以创建既安全又可复用的查询条件构建块。关键在于理解 TypeScript 的类型系统和 Kysely 的类型结构，找到两者之间的最佳结合点。