Null 和 Undefined

警告

在 Prisma ORM 5.20.0 之前，undefined 被视为一个特殊值，不会包含在生成的查询中。这种行为可能导致意外结果和数据丢失。如果您使用的是旧版本的 Prisma ORM，我们强烈建议更新到 5.20.0 或更高版本，以利用新的 strictUndefinedChecks 功能。

有关旧版行为的文档，请参阅旧版行为。

严格 undefined 检查（预览功能）

Prisma ORM 5.20.0 引入了一个名为 strictUndefinedChecks 的新预览功能。此功能更改了 Prisma Client 处理 undefined 值的方式，从而更好地防止意外数据丢失或意外的查询行为。

启用严格 undefined 检查

要启用此功能，请将以下内容添加到您的 Prisma schema

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["strictUndefinedChecks"]
}

使用严格 undefined 检查

启用此功能后

在查询中显式将字段设置为 undefined 将导致运行时错误。
要跳过查询中的字段，请使用新的 Prisma.skip 符号而不是 undefined。

用法示例

// This will throw an error
prisma.user.create({
  data: {
    name: 'Alice',
    email: undefined // Error: Cannot explicitly use undefined here
  }
})

// Use `Prisma.skip` (a symbol provided by Prisma) to omit a field
prisma.user.create({
  data: {
    name: 'Alice',
    email: Prisma.skip // This field will be omitted from the query
  }
})

此更改有助于防止意外删除或更新，例如

// Before: This would delete all users
prisma.user.deleteMany({
  where: {
    id: undefined
  }
})

// After: This will throw an error
Invalid \`prisma.user.deleteMany()\` invocation in
/client/tests/functional/strictUndefinedChecks/test.ts:0:0
  XX })
  XX 
  XX test('throws on undefined input field', async () => {
→ XX   const result = prisma.user.deleteMany({
         where: {
           id: undefined
               ~~~~~~~~~
         }
       })
Invalid value for argument \`where\`: explicitly \`undefined\` values are not allowed."

迁移路径

要迁移现有代码

// Before
let optionalEmail: string | undefined

prisma.user.create({
  data: {
    name: 'Alice',
    email: optionalEmail
  }
})

// After
prisma.user.create({
  data: {
    name: 'Alice',
    email: optionalEmail ?? Prisma.skip
  }
})

此新行为旨在成为 Prisma ORM 6 中的默认行为。

`exactOptionalPropertyTypes`

除了 strictUndefinedChecks 之外，我们还建议启用 TypeScript 编译器选项 exactOptionalPropertyTypes。此选项强制可选属性必须完全匹配，这有助于捕获代码中 undefined 值的潜在问题。虽然 strictUndefinedChecks 会为无效的 undefined 用法引发运行时错误，但 exactOptionalPropertyTypes 将在构建过程中捕获这些问题。

了解有关 exactOptionalPropertyTypes 的更多信息，请参阅 TypeScript 文档。

反馈

与往常一样，我们欢迎您对此功能提供反馈。请在 GitHub 讨论中分享您对此预览功能的想法和建议。

旧版行为

警告

如果您使用的是 Prisma ORM 5.19.1 或更早版本，则此部分相关。

Prisma Client 区分 null 和 undefined

null 是一个值
undefined 表示不执行任何操作

信息

在 带有 GraphQL 上下文的 Prisma ORM 中，这一点尤其重要，其中 null 和 undefined 是可互换的。

以下数据表示 User 表。以下所有示例中都将使用此数据集

id	name	email
1	Nikolas	[email protected]
2	Martin	[email protected]
3	empty	[email protected]
4	Tyler	[email protected]

影响多个记录的查询中的 `null` 和 `undefined`

本节将介绍 undefined 和 null 值如何影响与数据库中多个记录交互或创建多个记录的查询的行为。

Null

考虑以下 Prisma Client 查询，该查询搜索 name 值与提供的 null 值匹配的所有用户

const users = await prisma.user.findMany({
  where: {
    name: null,
  },
})

显示查询结果

[
  {
    "id": 3,
    "name": null,
    "email": "[email protected]"
  }
]

由于 null 作为 name 列的过滤器提供，Prisma Client 将生成一个查询，该查询搜索 User 表中 name 列为空的所有记录。

Undefined

现在考虑这样一种情况，即您使用 undefined 作为 name 列的过滤器值运行相同的查询

const users = await prisma.user.findMany({
  where: {
    name: undefined,
  },
})

显示查询结果

[
  {
    "id": 1,
    "name": "Nikolas",
    "email": "[email protected]"
  },
  {
    "id": 2,
    "name": "Martin",
    "email": "[email protected]"
  },
  {
    "id": 3,
    "name": null,
    "email": "[email protected]"
  },
  {
    "id": 4,
    "name": "Tyler",
    "email": "[email protected]"
  }
]

在过滤器中使用 undefined 值实际上是在告诉 Prisma Client 您已决定不为该列定义过滤器。

编写上述查询的等效方法是

const users = await prisma.user.findMany()

此查询将从 User 表中选择每一行。

信息

注意：在 Prisma Client 查询的参数对象中使用 undefined 作为任何键的值将导致 Prisma ORM 的行为就像根本没有提供该键一样。

尽管本节的示例侧重于 findMany 函数，但相同的概念适用于任何可以影响多个记录的函数，例如 updateMany 和 deleteMany。

影响一个记录的查询中的 `null` 和 `undefined`

本节将介绍 undefined 和 null 值如何影响与数据库中单个记录交互或创建单个记录的查询的行为。

警告

注意：null 不是 findUnique() 查询中的有效过滤器值。

在影响单个记录的查询的过滤器条件中使用 null 和 undefined 时的查询行为与上一节中描述的行为非常相似。

Null

考虑以下查询，其中 null 用于过滤 name 列

const user = await prisma.user.findFirst({
  where: {
    name: null,
  },
})

显示查询结果

[
  {
    "id": 3,
    "name": null,
    "email": "[email protected]"
  }
]

由于 null 用作 name 列的过滤器，Prisma Client 将生成一个查询，该查询搜索 User 表中 name 值为空的第一个记录。

Undefined

如果 undefined 用作 name 列的过滤器值，则查询的行为就像根本没有将过滤器条件传递给该列一样。

考虑以下查询

const user = await prisma.user.findFirst({
  where: {
    name: undefined,
  },
})

显示查询结果

[
  {
    "id": 1,
    "name": "Nikolas",
    "email": "[email protected]"
  }
]

在这种情况下，查询将返回数据库中的第一个记录。

表示上述查询的另一种方法是

const user = await prisma.user.findFirst()

尽管本节的示例侧重于 findFirst 函数，但相同的概念适用于任何影响单个记录的函数。

GraphQL 解析器中的 `null` 和 `undefined`

对于此示例，请考虑基于以下 Prisma schema 的数据库

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

在以下更新用户的 GraphQL mutation 中，authorEmail 和 name 都接受 null。从 GraphQL 的角度来看，这意味着字段是可选的

type Mutation {
  // Update author's email or name, or both - or neither!
  updateUser(id: Int!, authorEmail: String, authorName: String): User!
}

但是，如果您将 null 值传递给 authorEmail 或 authorName 到 Prisma Client，则会发生以下情况

如果 args.authorEmail 为 null，则查询将失败。email 不接受 null。
如果 args.authorName 为 null，则 Prisma Client 会将 name 的值更改为 null。这可能不是您希望更新的工作方式。

updateUser: (parent, args, ctx: Context) => {
  return ctx.prisma.user.update({
    where: { id: Number(args.id) },
    data: {
      email: args.authorEmail, // email cannot be null
      name: args.authorName // name set to null - potentially unwanted behavior
    },
  })
},

相反，如果输入值为 null，则将 email 和 name 的值设置为 undefined。这样做与根本不更新字段相同

updateUser: (parent, args, ctx: Context) => {
  return ctx.prisma.user.update({
    where: { id: Number(args.id) },
    data: {
      email: args.authorEmail != null ? args.authorEmail : undefined, // If null, do nothing
      name: args.authorName != null ? args.authorName : undefined // If null, do nothing
    },
  })
},