Evolu项目中Kysely数据库查询接口的扩展与限制探讨

背景介绍

Evolu是一个基于本地优先架构的数据管理库，它使用Kysely作为其SQL查询构建器。在项目开发过程中，开发者发现现有的Kysely接口只暴露了selectFrom和fn两个方法，这限制了某些高级查询功能的使用，特别是递归查询(CTE)等特性。

接口限制的现状

目前Evolu通过TypeScript的Pick工具类型，从Kysely接口中仅选择了两个方法：

type QueryCallback<S extends DatabaseSchema, R extends Row> = (
  db: Pick<Kysely.Kysely<QuerySchema<S>>, "selectFrom" | "fn">,
) => Kysely.SelectQueryBuilder<any, any, R>;

这种设计的主要目的是隐藏Kysely的变异(mutation)API，确保所有数据变更操作都通过Evolu提供的特定方式完成，而不是直接通过SQL语句。

扩展接口的需求

开发者希望添加.with和.withRecursive方法以支持公共表表达式(CTE)和递归查询。这在处理层级数据或复杂查询时非常有用，例如：

WITH RECURSIVE category_tree AS (
  SELECT id, name, parent_id FROM category WHERE id = ?
  UNION ALL
  SELECT c.id, c.name, c.parent_id FROM category c
  JOIN category_tree ct ON c.parent_id = ct.id
)
SELECT * FROM category_tree;

技术实现方案

直接扩展Pick类型看似简单：

type QueryCallback<S extends DatabaseSchema, R extends Row> = (
  db: Pick<
    Kysely.Kysely<QuerySchema<S>>,
    "selectFrom" | "fn" | "with" | "withRecursive"
  >,
) => Kysely.SelectQueryBuilder<any, any, R>;

然而，当尝试将Pick类型提取为单独的类型别名时，却遇到了复杂的类型兼容性问题。这表明Kysely的类型系统相当复杂，简单的重构可能会破坏类型推断。

安全性考量

在探索过程中，开发者发现.with和.withRecursive方法返回的构建器仍然暴露了变异方法，这与Evolu的设计理念相冲突。Kysely项目本身有一个关于只读类型的PR，但目前处于停滞状态。

临时解决方案

虽然不建议，但开发者可以通过类型断言临时获取完整的Kysely实例：

const myDB = db as Kysely<Database>;

这种方法需要谨慎使用，并应添加明确的警告，提醒开发者不要使用变异方法。

未来改进方向

1. 变异查询检测：需要在运行时检测并阻止包含变异操作的SQL查询
2. Kysely定制：可能需要修改Kysely源码，移除不需要的变异相关代码
3. 类型安全增强：探索更严格的类型限制方案，确保查询构建器不会意外暴露变异方法

总结

Evolu在平衡功能丰富性和安全性方面面临着挑战。虽然扩展Kysely接口可以带来更强大的查询能力，但也可能引入安全风险。目前最稳妥的做法是保持现有接口，等待Kysely官方对只读类型的支持，或者考虑对Kysely进行定制化修改。对于确实需要高级功能的开发者，可以通过类型断言临时突破限制，但必须自行承担风险。