类型安全
为 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 会推断它的类型应该是数字。
回到 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`