Kysely扩展指南：自定义表达式与类型安全构建

前言

Kysely作为一个类型安全的SQL查询构建器，其强大之处在于它提供了灵活的扩展机制。当内置功能无法满足特定需求时，开发者可以轻松地创建自定义表达式和构建器。本文将深入探讨如何扩展Kysely的功能，实现类型安全的自定义SQL表达式。

核心概念：Expression与AliasedExpression

Kysely的API设计围绕两个核心接口展开：

1. Expression：表示一个SQL表达式，包含类型信息T和转换为操作节点的方法
2. AliasedExpression<T, A>：在Expression基础上增加了别名信息，用于SELECT或FROM等需要命名的场景

理解这两个接口是扩展Kysely功能的关键。

创建自定义表达式

基础实现方式

我们可以通过实现Expression<T>接口来创建自定义表达式。以下是一个处理PostgreSQL JSON/JSONB值的示例：

class JsonValue<T> implements Expression<T> {
  #value: T

  constructor(value: T) {
    this.#value = value
  }

  get expressionType(): T | undefined {
    return undefined
  }

  toOperationNode(): OperationNode {
    const json = JSON.stringify(this.#value)
    return sql`CAST(${json} AS JSONB)`.toOperationNode()
  }
}

这种实现方式虽然完整，但在实际开发中往往过于繁琐。Kysely提供了更简便的方法。

简化实现方式

大多数情况下，我们可以直接使用sql模板标签和RawBuilder<T>来简化实现：

function json<T>(value: T): RawBuilder<T> {
  return sql`CAST(${JSON.stringify(value)} AS JSONB)`
}

这种简化方式不仅代码量少，而且功能完全相同，推荐在实际项目中使用。

带别名的表达式

当需要在SELECT或FROM子句中使用表达式时，我们需要为表达式提供别名。这时可以使用AliasedExpression<T, A>接口：

class AliasedJsonValue<T, A extends string> implements AliasedExpression<T, A> {
  #expression: Expression<T>
  #alias: A

  // ...实现细节...

  toOperationNode(): AliasNode {
    return AliasNode.create(
      this.#expression.toOperationNode(),
      IdentifierNode.create(this.#alias)
    )
  }
}

同样地，Kysely提供了简化方式，我们可以直接使用RawBuilder的as方法：

json({ someValue: 42 }).as('some_object')

复杂示例：VALUES子句实现

让我们看一个更复杂的例子，实现PostgreSQL中的VALUES子句：

function values<R extends Record<string, unknown>, A extends string>(
  records: R[],
  alias: A
): AliasedRawBuilder<R, A> {
  const keys = Object.keys(records[0])
  const values = sql.join(
    records.map((r) => sql`(${sql.join(keys.map((k) => r[k]))})`)
  )
  const wrappedAlias = sql.ref(alias)
  const wrappedColumns = sql.join(keys.map(sql.ref))
  const aliasSql = sql`${wrappedAlias}(${wrappedColumns})`
  
  return sql<R>`(values ${values})`.as<A>(aliasSql)
}

这个函数可以这样使用：

const records = [
  { id: 1, v1: 'foo', v2: 'bar' },
  { id: 2, v1: 'baz', v2: 'spam' }
]

db.insertInto('t')
  .columns(['t1', 't2'])
  .expression(
    db.selectFrom(values(records, 'v'))
      .innerJoin('j', 'v.id', 'j.vid')
      .select(['v.v1', 'j.j2'])
  )

扩展方式的选择

Kysely提供了多种扩展方式，各有优缺点：

1. 辅助函数：推荐方式，简单直接，类型安全
2. 继承：不推荐，容易遇到TypeScript类型系统限制
3. 模块增强：高级用法，可以扩展构建器类的方法

最佳实践建议

1. 优先使用sql模板标签和RawBuilder创建辅助函数
2. 保持辅助函数小而专一，每个函数只解决一个问题
3. 为复杂操作编写详细的类型定义
4. 避免过度扩展，只在确实需要时创建自定义表达式

总结

Kysely的扩展机制非常灵活，允许开发者根据项目需求创建类型安全的SQL表达式。通过理解Expression和AliasedExpression接口，以及熟练使用sql模板标签，我们可以轻松扩展Kysely的功能，同时保持代码的类型安全性。

记住，大多数情况下简单的辅助函数就能满足需求，只有在特殊场景下才需要实现完整的接口。保持代码简洁是使用Kysely扩展功能的关键。