Kysely中异步返回查询构建器的解决方案

背景介绍

Kysely是一个类型安全的SQL查询构建器，它提供了流畅的API来构建和执行数据库查询。在使用Kysely时，开发者可能会遇到一个常见问题：如何从异步函数中返回查询构建器(SelectQueryBuilder)实例。

问题现象

当开发者尝试从async函数返回一个查询构建器时，会遇到错误提示："don't await SelectQueryBuilder instances directly"。这是因为Kysely为了防止开发者错误地直接await查询构建器而不是调用execute方法，在查询构建器上实现了then方法。

技术原理

在JavaScript/TypeScript中，任何实现了then方法的对象都被视为"thenable"，可以被await操作符处理。Kysely利用这一特性，在查询构建器上添加了then方法，当开发者直接await查询构建器时会抛出错误，提醒开发者需要调用execute或executeTakeFirst方法。

解决方案

1. 使用对象包装查询构建器

最推荐的解决方案是将查询构建器包装在一个普通对象中返回：

private async makeQuery(db: Conn) {
    const filter = await getFilterArg(db);
    return { 
        query: db.selectFrom("item").where("item.fkId", "=", filter)
    }
}

使用时先解构出query再执行：

async getOne(db: Conn) {
    const { query } = await this.makeQuery(db);
    return await query.executeTakeFirst();
}

2. 返回工厂函数

另一种方式是返回一个创建查询的函数：

private async makeQuery(db: Conn) {
    const filter = await getFilterArg(db);
    return () => db.selectFrom("item").where("item.fkId", "=", filter);
}

使用时先调用函数获取查询：

async getOne(db: Conn) {
    const query = (await this.makeQuery(db))();
    return await query.executeTakeFirst();
}

3. 移除then属性(不推荐)

虽然技术上可行，但不推荐这种方式，因为它破坏了Kysely的设计意图：

private async makeQuery(db: Conn) {
    const filter = await getFilterArg(db);
    const query = db.selectFrom("item").where("item.fkId", "=", filter);
    Object.defineProperty(query, "then", { value: undefined });
    return query;
}

设计考量

Kysely团队选择这种设计有几个重要原因：

1. 防止开发者错误地直接await查询构建器
2. 保持与Knex等类似库的行为一致性
3. 通过类型系统强制正确的查询执行方式
4. 提供清晰的错误提示帮助开发者快速发现问题

最佳实践

1. 优先使用对象包装的方式，代码可读性更好
2. 避免修改查询构建器的内部属性
3. 保持查询构建和查询执行的逻辑分离
4. 利用TypeScript类型检查确保正确使用查询构建器

总结

Kysely通过防止直接await查询构建器的设计，强制开发者使用正确的方式执行查询。虽然这给某些使用场景带来了限制，但通过简单的包装模式可以轻松解决。理解这一设计背后的原理有助于开发者编写更健壮的数据库访问代码。