API 参考
加速 API 参考文档基于以下模式
model User {
id Int @id @default(autoincrement())
name String?
email String @unique
}
所有示例均基于 User
模型。
cacheStrategy
通过 Prisma Client 的加速扩展,您可以将 cacheStrategy
参数用于模型查询,并使用 ttl
和 swr
参数来定义加速的缓存策略。加速扩展要求您安装 Prisma Client 版本 4.10.0
。
选项
cacheStrategy
参数接受带有以下键的选项
选项 | 示例 | 类型 | 必需 | 描述 |
---|---|---|---|---|
swr | 60 | 整数 | 否 | 过时-同时-重新验证时间(秒)。 |
ttl | 60 | 整数 | 否 | 生存时间(秒)。 |
标签 | ["user"] | 字符串数组 | 否 | tag 充当变量,用于控制应用程序中特定查询的失效。它是一个可选的字符串数组,用于 使缓存失效,每个标签仅包含字母数字字符和下划线,最大长度为 64 个字符。 |
示例
向查询添加缓存策略,定义 60 秒的过时-同时-重新验证 (SWR) 值、60 秒的生存时间 (TTL) 值以及 "emails_with_alice"
的缓存标签
await prisma.user.findMany({
where: {
email: {
contains: "alice@prisma.io",
},
},
cacheStrategy: {
swr: 60,
ttl: 60,
tags: ["emails_with_alice"],
},
});
支持的 Prisma Client 操作
以下是支持 cacheStrategy
的所有读取查询操作的列表
findUnique()
findUniqueOrThrow()
findFirst()
findFirstOrThrow()
findMany()
count()
aggregate()
groupBy()
cacheStrategy
参数在任何写入操作(例如 create()
)中均不受支持。
withAccelerateInfo
任何支持 cacheStrategy
的查询都可以附加 withAccelerateInfo()
以包装响应数据并包含有关加速响应的其他信息。
要检索响应的状态,请使用
const { data, info } = await prisma.user
.count({
cacheStrategy: { ttl: 60, swr: 600 },
where: { myField: 'value' },
})
.withAccelerateInfo()
console.dir(info)
请注意响应对象的 info
属性。这是存储请求信息的位置。
返回类型
info
对象类型为 AccelerateInfo
,并遵循以下接口
interface AccelerateInfo {
cacheStatus: 'ttl' | 'swr' | 'miss' | 'none'
lastModified: Date
region: string
requestId: string
signature: string
}
属性 | 类型 | 描述 |
---|---|---|
cacheStatus | "ttl" | "swr" | "miss" | "none" | 响应的缓存状态。
|
lastModified | 日期 | 上次刷新响应的日期。 |
区域 | 字符串 | 接收请求的数据中心区域。 |
requestId | 字符串 | 请求的唯一标识符。对故障排除很有用。 |
签名 | 字符串 | Prisma 操作的唯一签名。 |
$accelerate.invalidate
您可以使用 $accelerate.invalidate
API 使缓存失效。
要按需使缓存的查询结果失效,需要付费计划。每个计划对每天允许的基于缓存标签的失效次数都有特定限制,但是调用 $accelerate.invalidate
API 本身没有限制。有关更多详细信息,请参阅我们的 定价。
示例
要使以下查询失效
await prisma.user.findMany({
where: {
email: {
contains: "alice@prisma.io",
},
},
cacheStrategy: {
swr: 60,
ttl: 60,
tags: ["emails_with_alice"],
},
});
您需要在 $accelerate.invalidate
API 中提供缓存标签
try {
await prisma.$accelerate.invalidate({
tags: ["emails_with_alice"],
});
} catch (e) {
if (e instanceof Prisma.PrismaClientKnownRequestError) {
// The .code property can be accessed in a type-safe manner
if (e.code === "P6003") {
console.log(
"The cache invalidation rate limit has been reached. Please try again later."
);
}
}
throw e;
}
每次调用最多可以使 5 个标签失效。
$accelerate.invalidateAll
您可以使用 $accelerate.invalidateAll
API 使整个缓存失效。
示例
要使以下查询失效
await prisma.user.findMany({
where: {
email: {
contains: "alice@prisma.io",
},
},
cacheStrategy: {
swr: 60,
ttl: 60,
tags: ["emails_with_alice"],
},
});
只需调用 $accelerate.invalidateAll
API
try {
await prisma.$accelerate.invalidateAll();
} catch (e) {
if (e instanceof Prisma.PrismaClientKnownRequestError) {
if (e.code === "P6003") {
console.log(
"The cache invalidation rate limit has been reached. Please try again later."
);
}
}
throw e;
}
为什么要使用 $accelerate.invalidateAll
?
与 invalidate("all")
等替代方案相比,此方法提供更好的编辑器支持(例如 IntelliSense)。
这将清除整个环境的缓存 — 请谨慎使用。
错误
Prisma 加速相关的错误以 P6xxx
开头。
您可以在此处找到 Prisma 加速的完整错误代码参考。