`query`:创建自定义 Prisma Client 查询
Prisma Client 扩展在 4.16.0 及更高版本中普遍可用。它们在 4.7.0 版本中以预览版形式引入。如果您运行的版本早于 4.16.0,请确保启用 clientExtensions
预览功能标志。
您可以使用 query
Prisma Client 扩展组件类型来接入查询生命周期,并修改传入的查询或其结果。
您可以使用 Prisma Client 扩展 query
组件来创建独立的客户端。这提供了一种替代中间件的方案。您可以将一个客户端绑定到特定筛选器或用户,将另一个客户端绑定到另一个筛选器或用户。例如,您可能这样做是为了在行级安全 (RLS) 扩展中实现用户隔离。此外,与中间件不同,query
扩展组件为您提供端到端的类型安全。了解更多关于 query
扩展与中间件的区别。
扩展 Prisma Client 查询操作
使用 $extends
客户端级别方法来创建一个扩展客户端。扩展客户端是标准 Prisma Client 的一个变体,它被一个或多个扩展包裹。
使用 query
扩展组件来修改查询。您可以按以下方式修改自定义查询:
要创建自定义查询,请使用以下结构
const prisma = new PrismaClient().$extends({
name?: 'name',
query?: {
user: { ... } // in this case, we add a query to the `user` model
},
});
属性如下
name
:(可选)指定扩展的名称,该名称会出现在错误日志中。query
:定义一个自定义查询。
修改特定模型中的特定操作
query
对象可以包含映射到 Prisma Client 操作名称的函数,例如 findUnique()
、findFirst
、findMany
、count
和 create
。以下示例修改 user.findMany
,使其使用自定义查询,只查找年龄大于 18 岁的用户。
const prisma = new PrismaClient().$extends({
query: {
user: {
async findMany({ model, operation, args, query }) {
// take incoming `where` and set `age`
args.where = { ...args.where, age: { gt: 18 } }
return query(args)
},
},
},
})
await prisma.user.findMany() // returns users whose age is greater than 18
在上述示例中,调用 prisma.user.findMany
会触发 query.user.findMany
。每个回调函数都会收到一个类型安全的 { model, operation, args, query }
对象,该对象描述了查询。此对象具有以下属性:
-
model
:我们要扩展的查询的包含模型的名称。在上述示例中,
model
是类型为"User"
的字符串。 -
operation
:正在扩展和执行的操作的名称。在上述示例中,
operation
是类型为"findMany"
的字符串。 -
args
:要扩展的特定查询输入信息。这是一个类型安全的对象,您可以在查询发生之前对其进行修改。您可以修改
args
中的任何属性。例外:您不能修改include
或select
,因为那会改变预期的输出类型并破坏类型安全。 -
query
:查询结果的 Promise。- 您可以使用
await
,然后修改此 Promise 的结果,因为其值是类型安全的。TypeScript 会捕获对象上的任何不安全修改。
- 您可以使用
修改 Schema 中所有模型中的特定操作
要扩展 Schema 中所有模型中的查询,请使用 $allModels
而不是特定的模型名称。例如:
const prisma = new PrismaClient().$extends({
query: {
$allModels: {
async findMany({ model, operation, args, query }) {
// set `take` and fill with the rest of `args`
args = { ...args, take: 100 }
return query(args)
},
},
},
})
修改特定模型中的所有操作
使用 $allOperations
来扩展特定模型中的所有操作。
例如,以下代码将自定义查询应用于 user
模型上的所有操作:
const prisma = new PrismaClient().$extends({
query: {
user: {
$allOperations({ model, operation, args, query }) {
/* your custom logic here */
return query(args)
},
},
},
})
修改所有 Prisma Client 操作
使用 $allOperations
方法来修改 Prisma Client 中存在的所有查询方法。$allOperations
可以用于模型操作和原始查询。
您可以按如下方式修改所有方法:
const prisma = new PrismaClient().$extends({
query: {
$allOperations({ model, operation, args, query }) {
/* your custom logic for modifying all Prisma Client operations here */
return query(args)
},
},
})
如果调用了原始查询,则传递给回调的 model
参数将为 undefined
。
例如,您可以使用 $allOperations
方法按如下方式记录查询:
const prisma = new PrismaClient().$extends({
query: {
async $allOperations({ operation, model, args, query }) {
const start = performance.now()
const result = await query(args)
const end = performance.now()
const time = end - start
console.log(
util.inspect(
{ model, operation, args, time },
{ showHidden: false, depth: null, colors: true }
)
)
return result
},
},
})
修改 Schema 中所有模型中的所有操作
使用 $allModels
和 $allOperations
来扩展 Schema 中所有模型中的所有操作。
将自定义查询应用于 Schema 中所有模型上的所有操作
const prisma = new PrismaClient().$extends({
query: {
$allModels: {
$allOperations({ model, operation, args, query }) {
/* your custom logic for modifying all operations on all models here */
return query(args)
},
},
},
})
修改顶层原始查询操作
要将自定义行为应用于特定的顶层原始查询操作,请使用顶层原始查询函数的名称,而不是模型名称。
- 关系型数据库
- MongoDB
const prisma = new PrismaClient().$extends({
query: {
$queryRaw({ args, query, operation }) {
// handle $queryRaw operation
return query(args)
},
$executeRaw({ args, query, operation }) {
// handle $executeRaw operation
return query(args)
},
$queryRawUnsafe({ args, query, operation }) {
// handle $queryRawUnsafe operation
return query(args)
},
$executeRawUnsafe({ args, query, operation }) {
// handle $executeRawUnsafe operation
return query(args)
},
},
})
const prisma = new PrismaClient().$extends({
query: {
$runCommandRaw({ args, query, operation }) {
// handle $runCommandRaw operation
return query(args)
},
},
})
修改查询结果
您可以使用 await
,然后修改 query
Promise 的结果。
const prisma = new PrismaClient().$extends({
query: {
user: {
async findFirst({ model, operation, args, query }) {
const user = await query(args)
if (user.password !== undefined) {
user.password = '******'
}
return user
},
},
},
})
我们包含上述示例是为了表明这是可能的。然而,出于性能原因,我们建议您使用result
组件类型来覆盖现有字段。在这种情况下,result
组件类型通常能提供更好的性能,因为它只在访问时进行计算。query
组件类型在查询执行后进行计算。
将查询包装成批处理事务
您可以将扩展查询包装到批处理事务中。例如,您可以使用此功能来实现行级安全 (RLS)。
以下示例扩展了 findFirst
,使其在批处理事务中运行。
const transactionExtension = Prisma.defineExtension((prisma) =>
prisma.$extends({
query: {
user: {
// Get the input `args` and a callback to `query`
async findFirst({ args, query, operation }) {
const [result] = await prisma.$transaction([query(args)]) // wrap the query in a batch transaction, and destructure the result to return an array
return result // return the first result found in the array
},
},
},
})
)
const prisma = new PrismaClient().$extends(transactionExtension)
查询扩展与中间件对比
您可以使用查询扩展或中间件来接入查询生命周期,并修改传入的查询或其结果。客户端扩展和中间件在以下方面有所不同:
- 中间件总是全局应用于同一个客户端。客户端扩展是隔离的,除非您有意地组合它们。了解更多关于客户端扩展的信息。
- 例如,在行级安全 (RLS) 场景中,您可以将每个用户保留在完全独立的客户端中。而使用中间件时,所有用户都在同一个客户端中活动。
- 在应用程序执行期间,使用扩展时,您可以选择一个或多个扩展客户端,或标准 Prisma Client。使用中间件时,您无法选择要使用的客户端,因为只有一个全局客户端。
- 扩展受益于端到端的类型安全和类型推断,而中间件则不然。
您可以在所有可以使用中间件的场景中使用 Prisma Client 扩展。
如果您同时使用 query
扩展组件和中间件
如果您在项目中同时使用 query
扩展组件和中间件,则适用以下规则和优先级:
- 在您的应用程序代码中,您必须在主 Prisma Client 实例上声明所有中间件。您不能在扩展客户端上声明它们。
- 在中间件和带有
query
组件的扩展执行的情况下,Prisma Client 会在执行带有query
组件的扩展之前执行中间件。Prisma Client 会按照您使用$use
或$extends
实例化它们的顺序执行各个中间件和扩展。