旧版 Nexus 到新版 Nexus

概述

信息

本指南尚未完全更新，因为它目前使用已弃用的 nexus-plugin-prisma 版本。虽然这仍然可用，但建议使用新的 nexus-prisma 库或替代的代码优先 GraphQL 库，例如 Pothos。如果您有任何疑问，请随时在我们的 Discord 上分享。

本升级指南描述了如何升级基于 Prisma 1 并且使用 nexus (< v0.12.0) 或 @nexus/schema 以及 nexus-prisma (< v4.0.0) 来实现 GraphQL 服务器的项目。

代码将被升级到 @nexus/schema 的最新版本。此外，nexus-prisma 包将被新的 nexus-plugin-prisma 替换。

本指南假设你已经完成了用于升级 Prisma ORM 层的指南。这意味着您已经

安装了 Prisma ORM 2 CLI
创建了你的 Prisma ORM 2 schema
内省了你的数据库并解决了潜在的 schema 不兼容性
安装并生成了 Prisma Client

本指南进一步假设你有一个类似于这样的文件设置

.
├── README.md
├── package.json
├── prisma
│   └── schema.prisma
├── prisma1
│   ├── datamodel.prisma
│   └── prisma.yml
└── src
    ├── generated
    │   ├── nexus-prisma
    │   ├── nexus.ts
    │   ├── prisma-client
    │   └── schema.graphql
    ├── types.ts
    └── index.ts

重要的部分是

一个名为 prisma 的文件夹，其中包含你的 Prisma ORM 2 schema
一个名为 src 的文件夹，其中包含你的应用程序代码

如果这不是你的项目结构，你需要调整指南中的说明以匹配你自己的设置。

1. 升级 Nexus 依赖项

要开始，你可以删除旧的 Nexus 和 Prisma 1 依赖项

npm uninstall nexus nexus-prisma prisma-client-lib prisma1

然后，你可以在你的项目中安装最新的 @nexus/schema 依赖项

npm install @nexus/schema

接下来，安装 Nexus 的 Prisma ORM 插件，它允许你在你的 GraphQL API 中公开 Prisma ORM 模型（这是以前的 nexus-prisma 包的新等效项）

npm install nexus-plugin-prisma

nexus-plugin-prisma 依赖项捆绑了所有必需的 Prisma ORM 依赖项。因此，你应该删除在升级应用程序的 Prisma ORM 层时添加安装的依赖项

npm uninstall @prisma/cli @prisma/client

但请注意，你仍然可以使用熟悉的命令调用 Prisma ORM 2 CLI

npx prisma -v

注意：如果你在运行 npx prisma -v 时看到 Prisma 1 CLI 的输出，请务必删除你的 node_modules 文件夹并重新运行 npm install。

2. 更新 Nexus 和 Prisma ORM 的配置

要开始，你可以删除新的设置不再需要的旧导入

import { makePrismaSchema, prismaObjectType } from 'nexus-prisma'
import datamodelInfo from './generated/nexus-prisma'
import { prisma } from './generated/prisma-client'

相反，你现在将以下内容导入到你的应用程序中

import { nexusSchemaPrisma } from 'nexus-plugin-prisma/schema'
import { objectType, makeSchema, queryType, mutationType } from '@nexus/schema'
import { PrismaClient } from '@prisma/client'

接下来，你需要调整你当前创建 GraphQLSchema 的代码，最有可能的是，这目前通过你代码中的 makePrismaSchema 函数发生。由于此函数是从已删除的 nexus-prisma 包导入的，你需要将其替换为 @nexus/schema 包中的 makeSchema 函数。最新版本中 Nexus 的 Prisma ORM 插件的使用方式也发生了变化。

这是一个这样的配置的例子

./src/index.ts

 const schema = makePrismaSchema({
 const schema = makeSchema({

  // Provide all the GraphQL types we've implemented
  types: [Query, Mutation, UserUniqueInput, User, Post, Category, Profile],

  // Configure the interface to Prisma
  prisma: {
    datamodelInfo,
    client: prisma,
  },
  plugins: [nexusSchemaPrisma({
    experimentalCRUD: true,
  })],

  // Specify where Nexus should put the generated files
  outputs: {
    schema: path.join(__dirname, './generated/schema.graphql'),
    typegen: path.join(__dirname, './generated/nexus.ts'),
  },

  // Configure nullability of input arguments: All arguments are non-nullable by default
  nonNullDefaults: {
    input: false,
    output: false,
  },

  // Configure automatic type resolution for the TS representations of the associated types
  typegenAutoConfig: {
    sources: [
      {
        source: path.join(__dirname, './types.ts'),
        alias: 'types',
      },
    ],
    contextType: 'types.Context',
  },
})

如果你之前对传递给你的解析器链的 GraphQL context 对象进行了类型化，你需要像这样调整类型

./src/types.ts

import { Prisma } from './generated/prisma-client'
import { PrismaClient } from '@prisma/client'

export interface Context {
  prisma: Prisma
  prisma: PrismaClient
}

3. 迁移你的 GraphQL 类型

以下是使用最新版本的 @nexus/schema 和 nexus-plugin-prisma 创建 GraphQL 类型的两种方法之间的主要差异的快速概述。

prismaObjectType 函数不再可用，所有类型都使用 Nexus 的 objectType 函数创建。
要通过 Nexus 暴露 Prisma 模型，可以使用 t.model 属性，该属性会添加到传递给 Nexus 的 definition 函数的 t 参数中。t.model 使您可以访问 Prisma 模型的属性并暴露它们。
通过 Nexus 暴露 Prisma 模型的 CRUD 操作也遵循类似的方法。这些操作通过 queryType 和 mutationType 类型的 definition 函数中的 t.crud 暴露。

3.1. 迁移 `Post` 类型

使用之前的 `nexus-prisma` 包的类型定义

在示例应用程序中，User 类型的定义如下

const User = prismaObjectType({
  name: 'User',
  definition(t) {
    t.prismaFields([
      'id',
      'name',
      'email',
      'jsonData',
      'role'
      {
        name: 'posts',
        args: [], // remove the arguments from the `posts` field of the `User` type in the Prisma schema
      },
    ])
  },
})

使用最新版本的 `@nexus/schema` 和 `nexus-plugin-prisma` 的类型定义

使用最新版本的 @nexus/schema，您现在可以在主 schema 实例上访问 objectType 函数，并像这样暴露 Prisma 模型的所有字段

const User = objectType({
  name: 'User',
  definition(t) {
    t.model.id()
    t.model.name()
    t.model.email()
    t.model.jsonData()
    t.model.role()
    t.model.posts({
      pagination: false,
      ordering: false,
      filtering: false,
    })
    t.model.profile()
  },
})

请注意，t.model 会查看传递给 objectType 函数的对象的 name 属性，并将其与 Prisma schema 中的模型进行匹配。在本例中，它与 User 模型匹配。因此，t.model 会暴露以 User 模型的字段命名的函数。

此时，您可能会在关联字段 posts 和 profile 上看到错误，例如：

//delete-next-line
Missing type Post, did you forget to import a type to the root query?

这是因为您尚未将 Post 和 Profile 类型添加到 GraphQL schema 中，一旦这些类型也成为 GraphQL schema 的一部分，错误就会消失！

3.2. 迁移 `Post` 类型

使用之前的 `nexus-prisma` 包的类型定义

在示例应用程序中，Post 类型的定义如下

const Post = prismaObjectType({
  name: 'Post',
  definition(t) {
    t.prismaFields(['*'])
  },
})

prismaFields 中的星号表示暴露所有 Prisma 字段。

使用最新版本的 `@nexus/schema` 和 `nexus-plugin-prisma` 的类型定义

使用最新版本的 @nexus/schema，您需要显式暴露所有字段，没有选项可以仅暴露 Prisma 模型中的所有内容。

因此，Post 的新定义必须显式列出其所有字段

const Post = objectType({
  name: 'Post',
  definition(t) {
    t.model.id()
    t.model.title()
    t.model.content()
    t.model.published()
    t.model.author()
    t.model.categories()
  },
})

请注意，t.model 会查看 name 属性，并将其与 Prisma schema 中的模型进行匹配。在本例中，它与 Post 模型匹配。因此，t.model 会暴露以 Post 模型的字段命名的函数。

3.3. 迁移 `Profile` 类型

使用之前的 `nexus-prisma` 包的类型定义

在示例应用程序中，Profile 类型的定义如下

const Profile = prismaObjectType({
  name: 'Profile',
  definition(t) {
    t.prismaFields(['*'])
  },
})

prismaFields 中的星号表示暴露所有 Prisma 字段。

使用最新版本的 `@nexus/schema` 和 `nexus-plugin-prisma` 的类型定义

使用最新版本的 @nexus/schema，您需要显式暴露所有字段，没有选项可以仅暴露 Prisma 模型中的所有内容。

因此，Profile 的新定义必须显式列出其所有字段

const Profile = objectType({
  name: 'Profile',
  definition(t) {
    t.model.id()
    t.model.bio()
    t.model.user()
    t.model.userId()
  },
})

请注意，t.model 会查看 name 属性，并将其与 Prisma schema 中的模型进行匹配。在本例中，它与 Profile 模型匹配。因此，t.model 会暴露以 Profile 模型的字段命名的函数。

3.4. 迁移 `Category` 类型

使用之前的 `nexus-prisma` 包的类型定义

在示例应用程序中，Category 类型的定义如下

const Category = prismaObjectType({
  name: 'Category',
  definition(t) {
    t.prismaFields(['*'])
  },
})

prismaFields 中的星号表示暴露所有 Prisma ORM 字段。

使用最新版本的 `@nexus/schema` 和 `nexus-plugin-prisma` 的类型定义

使用最新版本的 @nexus/schema，您需要显式暴露所有字段，没有选项可以仅暴露 Prisma 模型中的所有内容。

因此，Category 的新定义必须显式列出其所有字段

const Category = objectType({
  name: 'Category',
  definition(t) {
    t.model.id()
    t.model.name()
    t.model.posts({
      pagination: true,
      ordering: true,
      filtering: true,
    })
  },
})

请注意，t.model 会查看 name 属性，并将其与 Prisma schema 中的模型进行匹配。在本例中，它与 Category 模型匹配。因此，t.model 会暴露以 Category 模型的字段命名的函数。

4. 迁移 GraphQL 操作

下一步，您可以开始将所有 GraphQL *查询* 和 *mutation* 从“之前”的 GraphQL API 迁移到新的 API。

在本指南中，将使用以下示例 GraphQL 操作

input UserUniqueInput {
  id: String
  email: String
}

type Query {
  posts(searchString: String): [Post!]!
  user(userUniqueInput: UserUniqueInput!): User
  users(where: UserWhereInput, orderBy: Enumerable<UserOrderByInput>, skip: Int, after: String, before: String, first: Int, last: Int): [User]!
}

type Mutation {
  createUser(data: UserCreateInput!): User!
  createDraft(title: String!, content: String, authorId: ID!): Post
  updateBio(userUniqueInput: UserUniqueInput!, bio: String!): User
  addPostToCategories(postId: String!, categoryIds: [String!]!): Post
}

4.1. 迁移 GraphQL 查询

在本节中，您将把所有 GraphQL *查询* 从之前的 nexus 和 nexus-prisma 版本迁移到最新版本的 @nexus/schema 和 nexus-plugin-prisma。

4.1.1. 迁移 `users` 查询

在我们的示例 API 中，示例 GraphQL schema 中的 users 查询实现如下。

const Query = prismaObjectType({
  name: 'Query',
  definition(t) {
    t.prismaFields(['users'])
  },
})

要使用新的 Nexus 获得相同的行为，您需要在 t.crud 上调用 users 函数

schema.queryType({
  definition(t) {
    t.crud.users({
      filtering: true,
      ordering: true,
      pagination: true,
    })
  },
})

回想一下，crud 属性由 nexus-plugin-prisma 添加到 t（使用与 t.model 相同的机制）。

4.1.2. 迁移 `posts(searchString: String): [Post!]!` 查询

在示例 API 中，posts 查询实现如下

queryType({
  definition(t) {
    t.list.field('posts', {
      type: 'Post',
      args: {
        searchString: stringArg({ nullable: true }),
      },
      resolve: (parent, { searchString }, context) => {
        return context.prisma.posts({
          where: {
            OR: [
              { title_contains: searchString },
              { content_contains: searchString },
            ],
          },
        })
      },
    })
  },
})

对于此查询，唯一需要更新的是对 Prisma ORM 的调用，因为新的 Prisma Client API 与 Prisma 1 中使用的 API 略有不同。

queryType({
  definition(t) {
    t.list.field('posts', {
      type: 'Post',
      args: {
        searchString: stringArg({ nullable: true }),
      },
      resolve: (parent, { searchString }, context) => {
        return context.prisma.post.findMany({
          where: {
            OR: [
              { title: { contains: searchString } },
              { content: { contains: searchString } },
            ],
          },
        })
      },
    })
  },
})

请注意，db 对象由 nexus-plugin-prisma 自动附加到 context。它代表您的 PrismaClient 的一个实例，使您能够在解析器中向数据库发送查询。

4.1.3. 迁移 `user(uniqueInput: UserUniqueInput): User` 查询

在示例 API 中，user 查询实现如下

inputObjectType({
  name: 'UserUniqueInput',
  definition(t) {
    t.string('id')
    t.string('email')
  },
})

queryType({
  definition(t) {
    t.field('user', {
      type: 'User',
      args: {
        userUniqueInput: schema.arg({
          type: 'UserUniqueInput',
          nullable: false,
        }),
      },
      resolve: (_, args, context) => {
        return context.prisma.user({
          id: args.userUniqueInput?.id,
          email: args.userUniqueInput?.email,
        })
      },
    })
  },
})

现在您需要调整对 prisma 实例的调用，因为新的 Prisma Client API 与 Prisma 1 中使用的 API 略有不同。

const Query = queryType({
  definition(t) {
    t.field('user', {
      type: 'User',
      args: {
        userUniqueInput: arg({
          type: 'UserUniqueInput',
          nullable: false,
        }),
      },
      resolve: (_, args, context) => {
        return context.prisma.user.findUnique({
          where: {
            id: args.userUniqueInput?.id,
            email: args.userUniqueInput?.email,
          },
        })
      },
    })
  },
})

4.2. 迁移 GraphQL mutations

在本节中，您将把示例 schema 中的 GraphQL mutation 迁移到最新版本的 @nexus/schema 和 nexus-plugin-prisma。

4.2.1. 迁移 `createUser` mutation

在我们的示例 API 中，示例 GraphQL schema 中的 createUser mutation 实现如下。

const Mutation = prismaObjectType({
  name: 'Mutation',
  definition(t) {
    t.prismaFields(['createUser'])
  },
})

要使用最新版本的 @nexus/schema 和 nexus-plugin-prisma 获得相同的行为，您需要在 t.crud 上调用 createOneUser 函数，并传递一个 alias 以便在您的 GraphQL schema 中将该字段重命名为 createUser（否则，它将被称为 createOneUser，以使用的函数命名）

const Query = queryType({
  definition(t) {
    t.crud.createOneUser({
      alias: 'createUser',
    })
  },
})

回想一下，crud 属性由 nexus-plugin-prisma 添加到 t（使用与 t.model 相同的机制）。

4.2.2. 迁移 `createDraft(title: String!, content: String, authorId: String!): Post!` 查询

在示例应用程序中，createDraft mutation 实现如下。

mutationType({
  definition(t) {
    t.field('createDraft', {
      type: 'Post',
      args: {
        title: stringArg({ nullable: false }),
        content: stringArg(),
        authorId: stringArg({ nullable: false }),
      },
      resolve: (_, args, context) => {
        return context.prisma.createPost({
          title: args.title,
          content: args.content,
          author: {
            connect: { id: args.authorId },
          },
        })
      },
    })
  },
})

现在您需要调整对 prisma 实例的调用，因为新的 Prisma Client API 与 Prisma 1 中使用的 API 略有不同。

const Mutation = mutationType({
  definition(t) {
    t.field('createDraft', {
      type: 'Post',
      args: {
        title: stringArg({ nullable: false }),
        content: stringArg(),
        authorId: stringArg({ nullable: false }),
      },
      resolve: (_, args, context) => {
        return context.prisma.post.create({
          data: {
            title: args.title,
            content: args.content,
            author: {
              connect: { id: args.authorId },
            },
          },
        })
      },
    })
  },
})

4.2.3. 迁移 `updateBio(bio: String, userUniqueInput: UserUniqueInput!): User` mutation

在示例 API 中，updateBio mutation 的定义和实现如下。

mutationType({
  definition(t) {
    t.field('updateBio', {
      type: 'User',
      args: {
        userUniqueInput: arg({
          type: 'UserUniqueInput',
          nullable: false,
        }),
        bio: stringArg(),
      },
      resolve: (_, args, context) => {
        return context.prisma.updateUser({
          where: {
            id: args.userUniqueInput?.id,
            email: args.userUniqueInput?.email,
          },
          data: {
            profile: {
              create: { bio: args.bio },
            },
          },
        })
      },
    })
  },
})

现在您需要调整对 prisma 实例的调用，因为新的 Prisma Client API 与 Prisma 1 中使用的 API 略有不同。

const Mutation = mutationType({
  definition(t) {
    t.field('updateBio', {
      type: 'User',
      args: {
        userUniqueInput: arg({
          type: 'UserUniqueInput',
          nullable: false,
        }),
        bio: stringArg(),
      },
      resolve: (_, args, context) => {
        return context.prisma.user.update({
          where: {
            id: args.userUniqueInput?.id,
            email: args.userUniqueInput?.email,
          },
          data: {
            profile: {
              create: { bio: args.bio },
            },
          },
        })
      },
    })
  },
})

4.2.4. 迁移 `addPostToCategories(postId: String!, categoryIds: [String!]!): Post` mutation

在示例 API 中，addPostToCategories mutation 的定义和实现如下。

mutationType({
  definition(t) {
    t.field('addPostToCategories', {
      type: 'Post',
      args: {
        postId: stringArg({ nullable: false }),
        categoryIds: stringArg({
          list: true,
          nullable: false,
        }),
      },
      resolve: (_, args, context) => {
        const ids = args.categoryIds.map((id) => ({ id }))
        return context.prisma.updatePost({
          where: {
            id: args.postId,
          },
          data: {
            categories: { connect: ids },
          },
        })
      },
    })
  },
})

现在您需要调整对 prisma 实例的调用，因为新的 Prisma Client API 与 Prisma 1 中使用的 API 略有不同。

const Mutation = mutationType({
  definition(t) {
    t.field('addPostToCategories', {
      type: 'Post',
      args: {
        postId: stringArg({ nullable: false }),
        categoryIds: stringArg({
          list: true,
          nullable: false,
        }),
      },
      resolve: (_, args, context) => {
        const ids = args.categoryIds.map((id) => ({ id }))
        return context.prisma.post.update({
          where: {
            id: args.postId,
          },
          data: {
            categories: { connect: ids },
          },
        })
      },
    })
  },
})

5. 清理

5.1. 清理 npm 依赖项

如果您尚未这样做，您现在可以卸载与 Prisma 1 设置相关的依赖项

npm uninstall prisma1 prisma-client-lib

5.2. 删除未使用的文件

接下来，删除 Prisma 1 设置的文件

rm -rf src/generated
rm -rf prisma1

5.3. 停止 Prisma ORM 服务器

最后，您可以停止运行您的 Prisma ORM 服务器。

概述​

1. 升级 Nexus 依赖项​

2. 更新 Nexus 和 Prisma ORM 的配置​

3. 迁移你的 GraphQL 类型​

3.1. 迁移 Post 类型​

使用之前的 nexus-prisma 包的类型定义​

使用最新版本的 @nexus/schema 和 nexus-plugin-prisma 的类型定义​

3.2. 迁移 Post 类型​

使用之前的 nexus-prisma 包的类型定义​

使用最新版本的 @nexus/schema 和 nexus-plugin-prisma 的类型定义​

3.3. 迁移 Profile 类型​

使用之前的 nexus-prisma 包的类型定义​

使用最新版本的 @nexus/schema 和 nexus-plugin-prisma 的类型定义​

3.4. 迁移 Category 类型​

使用之前的 nexus-prisma 包的类型定义​

使用最新版本的 @nexus/schema 和 nexus-plugin-prisma 的类型定义​

4. 迁移 GraphQL 操作​

4.1. 迁移 GraphQL 查询​

4.1.1. 迁移 users 查询​

4.1.2. 迁移 posts(searchString: String): [Post!]! 查询​

4.1.3. 迁移 user(uniqueInput: UserUniqueInput): User 查询​

4.2. 迁移 GraphQL mutations​

4.2.1. 迁移 createUser mutation​

4.2.2. 迁移 createDraft(title: String!, content: String, authorId: String!): Post! 查询​

4.2.3. 迁移 updateBio(bio: String, userUniqueInput: UserUniqueInput!): User mutation​

4.2.4. 迁移 addPostToCategories(postId: String!, categoryIds: [String!]!): Post mutation​

5. 清理​

5.1. 清理 npm 依赖项​

5.2. 删除未使用的文件​

5.3. 停止 Prisma ORM 服务器​

概述

1. 升级 Nexus 依赖项

2. 更新 Nexus 和 Prisma ORM 的配置

3. 迁移你的 GraphQL 类型

3.1. 迁移 `Post` 类型

使用之前的 `nexus-prisma` 包的类型定义

使用最新版本的 `@nexus/schema` 和 `nexus-plugin-prisma` 的类型定义

3.2. 迁移 `Post` 类型

使用之前的 `nexus-prisma` 包的类型定义

使用最新版本的 `@nexus/schema` 和 `nexus-plugin-prisma` 的类型定义

3.3. 迁移 `Profile` 类型

使用之前的 `nexus-prisma` 包的类型定义

使用最新版本的 `@nexus/schema` 和 `nexus-plugin-prisma` 的类型定义

3.4. 迁移 `Category` 类型

使用之前的 `nexus-prisma` 包的类型定义

使用最新版本的 `@nexus/schema` 和 `nexus-plugin-prisma` 的类型定义

4. 迁移 GraphQL 操作

4.1. 迁移 GraphQL 查询

4.1.1. 迁移 `users` 查询

4.1.2. 迁移 `posts(searchString: String): [Post!]!` 查询

4.1.3. 迁移 `user(uniqueInput: UserUniqueInput): User` 查询

4.2. 迁移 GraphQL mutations

4.2.1. 迁移 `createUser` mutation

4.2.2. 迁移 `createDraft(title: String!, content: String, authorId: String!): Post!` 查询

4.2.3. 迁移 `updateBio(bio: String, userUniqueInput: UserUniqueInput!): User` mutation

4.2.4. 迁移 `addPostToCategories(postId: String!, categoryIds: [String!]!): Post` mutation

5. 清理

5.1. 清理 npm 依赖项

5.2. 删除未使用的文件

5.3. 停止 Prisma ORM 服务器