类型安全
Prisma Client 生成的代码包含多种有用的类型和工具,可用于提高应用程序的类型安全性。本页介绍如何利用这些类型和工具的模式。
注意:如果你对 Prisma ORM 的高级类型安全主题感兴趣,请务必查看这篇关于使用新的 TypeScript
satisfies
关键字改进 Prisma Client 工作流程的博客文章。
导入生成的类型
你可以导入 Prisma
命名空间,并使用点符号访问类型和工具。以下示例展示了如何导入 Prisma
命名空间并使用它来访问和使用 Prisma.UserSelect
生成的类型
import { Prisma } from '@prisma/client'
// Build 'select' object
const userEmail: Prisma.UserSelect = {
email: true,
}
// Use select object
const createUser = await prisma.user.create({
data: {
email: 'bob@prisma.io',
},
select: userEmail,
})
另请参阅:使用 Prisma.UserCreateInput
生成的类型
什么是生成的类型?
生成的类型是派生自模型的 TypeScript 类型。你可以使用它们创建类型化的对象,并将其传递给顶级方法,例如 prisma.user.create(...)
或 prisma.user.update(...)
,或传递给 select
或 include
等选项。
例如,select
接受一个 UserSelect
类型的对象。其对象属性与根据模型由 select
语句支持的属性匹配。
下面的第一个选项卡显示了 UserSelect
生成的类型以及对象上的每个属性如何具有类型注解。第二个选项卡显示了生成该类型的原始 schema。
- 生成的类型
- 模型
type Prisma.UserSelect = {
id?: boolean | undefined;
email?: boolean | undefined;
name?: boolean | undefined;
posts?: boolean | Prisma.PostFindManyArgs | undefined;
profile?: boolean | Prisma.ProfileArgs | undefined;
}
model User {
id Int @id @default(autoincrement())
email String @unique
name String?
posts Post[]
profile Profile?
}
在 TypeScript 中,类型注解 的概念是指声明一个变量并添加类型注解来描述变量的类型。请参阅下面的示例。
const myAge: number = 37
const myName: string = 'Rich'
这两个变量声明都添加了类型注解,以指定它们分别是什么原始类型,即 number
和 string
。大多数情况下,这种注解是不需要的,因为 TypeScript 会根据变量的初始化方式推断其类型。在上面的示例中,myAge
使用数字进行了初始化,因此 TypeScript 推断它应该被类型化为 number。
回到 UserSelect
类型,如果你对创建的对象 userEmail
使用点符号,你将能够访问 User
模型上所有可以通过 select
语句进行交互的字段。
model User {
id Int @id @default(autoincrement())
email String @unique
name String?
posts Post[]
profile Profile?
}
import { Prisma } from '@prisma/client'
const userEmail: Prisma.UserSelect = {
email: true,
}
// properties available on the typed object
userEmail.id
userEmail.email
userEmail.name
userEmail.posts
userEmail.profile
同样地,你可以使用 include
生成的类型为对象指定类型,然后你的对象将能够访问那些可以使用 include
语句的属性。
import { Prisma } from '@prisma/client'
const userPosts: Prisma.UserInclude = {
posts: true,
}
// properties available on the typed object
userPosts.posts
userPosts.profile
有关可用不同类型的更多信息,请参阅模型查询选项参考。
生成的 UncheckedInput
类型
UncheckedInput
类型是一组特殊的生成的类型,允许你执行 Prisma Client 认为是“不安全”的操作,例如直接写入关系标量字段。在执行 create
、update
或 upsert
等操作时,你可以选择“安全”的 Input
类型或“不安全”的 UncheckedInput
类型。
例如,这个 Prisma schema 在 User
和 Post
之间有一个一对多的关系
model Post {
id Int @id @default(autoincrement())
title String @db.VarChar(255)
content String?
author User @relation(fields: [authorId], references: [id])
authorId Int
}
model User {
id Int @id @default(autoincrement())
email String @unique
name String?
posts Post[]
}
第一个选项卡显示 PostUncheckedCreateInput
生成的类型。它包含 authorId
属性,这是一个关系标量字段。第二个选项卡显示了一个使用 PostUncheckedCreateInput
类型的查询示例。如果 id 为 1
的用户不存在,此查询将导致错误。
- 生成的类型
- 查询示例
type PostUncheckedCreateInput = {
id?: number
title: string
content?: string | null
authorId: number
}
prisma.post.create({
data: {
title: 'First post',
content: 'Welcome to the first post in my blog...',
authorId: 1,
},
})
同样的查询可以使用“更安全”的 PostCreateInput
类型重写。这种类型不包含 authorId
字段,而是包含 author
关系字段。
- 生成的类型
- 查询示例
type PostCreateInput = {
title: string
content?: string | null
author: UserCreateNestedOneWithoutPostsInput
}
type UserCreateNestedOneWithoutPostsInput = {
create?: XOR<
UserCreateWithoutPostsInput,
UserUncheckedCreateWithoutPostsInput
>
connectOrCreate?: UserCreateOrConnectWithoutPostsInput
connect?: UserWhereUniqueInput
}
prisma.post.create({
data: {
title: 'First post',
content: 'Welcome to the first post in my blog...',
author: {
connect: {
id: 1,
},
},
},
})
如果 id 为 1
的作者不存在,此查询也会导致错误。在这种情况下,Prisma Client 会提供更具描述性的错误消息。你还可以使用 connectOrCreate
API 安全地创建一个新用户,如果具有给定 id 的用户尚不存在。
我们建议尽可能使用“安全”的 Input
类型。
类型工具
此功能从 Prisma ORM 4.9.0 版本开始可用。
为了帮助你创建高度类型安全的应用程序,Prisma Client 提供了一组利用输入和输出类型的类型工具。这些类型是完全动态的,这意味着它们会适应任何给定的模型和 schema。你可以使用它们来改进项目的自动补全和开发者体验。
这在验证输入和共享 Prisma Client 扩展中特别有用。
Prisma Client 中提供以下类型工具
Exact<Input, Shape>
:强制对Input
进行严格的类型安全检查。Exact
确保泛型类型Input
严格遵循你在Shape
中指定的类型。它将Input
收窄 到最精确的类型。Args<Type, Operation>
:检索给定模型和操作的输入参数。这对于想要执行以下操作的扩展作者特别有用- 重用现有类型来扩展或修改它们。
- 享受与现有操作相同的自动补全体验。
Result<Type, Arguments, Operation>
:接受输入参数并为给定模型和操作提供结果。通常与Args
一起使用。与Args
一样,Result
可帮助你重用现有类型来扩展或修改它们。Payload<Type, Operation>
:检索给定模型和操作的结果的完整结构,包括标量和关系对象。例如,你可以使用它在类型级别确定哪些键是标量或对象。
举个例子,这里有一个快速方法,可以强制函数的参数与将传递给 post.create
的内容匹配
type PostCreateBody = Prisma.Args<typeof prisma.post, 'create'>['data']
const addPost = async (postBody: PostCreateBody) => {
const post = await prisma.post.create({ data: postBody })
return post
}
await addPost(myData)
// ^ guaranteed to match the input of `post.create`