Kysely 库中构建器的管道方法优化探讨

Kysely 是一个强大的 TypeScript SQL 查询构建器，以其类型安全和灵活的 API 设计著称。在实际开发中，开发者经常会遇到需要复用某些查询构建逻辑的场景。本文探讨了如何通过优化构建器方法来实现更优雅的代码复用。

问题背景

在 Kysely 中创建表时，经常会遇到需要为表添加标准字段的情况。例如，很多表都需要一个 UUID 类型的主键 ID 字段。开发者通常会这样编写代码：

db.schema
  .createTable("my_table")
  .ifNotExists()
  .addColumn("id", "uuid", (b) => b.primaryKey().defaultTo(sql`uuid_generate_v4()`))

当这种模式在多个地方重复使用时，开发者自然会想到将其提取为可复用的函数。

现有解决方案

目前，开发者可以这样提取和复用代码：

function addId(t: CreateTableBuilder) {
  return t.addColumn("id", "uuid", (b) => b.primaryKey().defaultTo(sql`uuid_generate_v4()`))
}

// 使用方式
addId(
  db.schema
    .createTable("my_table")
    .ifNotExists()
)

这种方式虽然可行，但代码结构不够直观，特别是当构建链较长时，函数调用会打断流畅的链式调用体验。

更优的方案：$call 方法

Kysely 实际上已经提供了一个优雅的解决方案——$call 方法。这个方法允许开发者在构建链中插入自定义的函数调用，保持代码的连贯性：

db.schema
  .createTable("my_table")
  .ifNotExists()
  .$call(addId)

$call 方法的设计初衷正是为了解决这类代码复用问题。它接收一个函数作为参数，将该构建器实例传递给函数，并将函数返回值继续传递下去，完美保持了链式调用的流畅性。

方法命名的思考

关于 $call 方法的命名，开发团队有过深入讨论。最初考虑过 map 或 pipe 这样的名称，但存在以下考量：

1. map 可能会让来自 Knex 背景的开发者误以为这是对查询结果的映射操作
2. pipe 在函数式编程中通常表示一系列操作的串联，而 $call 只执行单一操作
3. $modify 也是一个候选名称，因为它更准确地描述了方法的目的——修改查询构建器

最终团队选择了 $call 这个名称，既避免了歧义，又清晰地表达了方法的用途。

实际应用建议

在实际项目中，推荐以下模式来组织常用的构建器修改函数：

// 定义常用修改函数
const tableModifiers = {
  withTimestamps(t: CreateTableBuilder) {
    return t
      .addColumn("created_at", "timestamp", (col) => col.notNull().defaultTo(sql`now()`))
      .addColumn("updated_at", "timestamp", (col) => col.notNull().defaultTo(sql`now()`))
  },
  withSoftDelete(t: CreateTableBuilder) {
    return t.addColumn("deleted_at", "timestamp")
  }
}

// 使用方式
db.schema
  .createTable("users")
  .$call(tableModifiers.withTimestamps)
  .$call(tableModifiers.withSoftDelete)

这种模式不仅提高了代码复用性，还使表结构的定义更加清晰和模块化。

总结

Kysely 的 $call 方法为查询构建器的复用提供了优雅的解决方案。通过将常用的构建逻辑封装成函数，开发者可以创建出更简洁、更易维护的数据库操作代码。虽然方法命名经过多方考量，但 $call 已经能够很好地满足大多数使用场景，是 Kysely API 设计中一个实用而强大的特性。