GraphQL 概述

除了 REST 和 Local API 之外，Payload 还内置了一个功能全面且可扩展的 GraphQL API。

默认情况下，GraphQL API 通过 /api/graphql 路径暴露，但你可以在主 Payload 配置中通过指定 routes 来自定义这个 URL。

你为 Collections 和 Globals 提供的标签(label)会被用来命名对应的 GraphQL 类型。特殊字符和空格会被自动移除。

GraphQL 配置选项

你可以在 Payload 配置的顶部定义所有管理 GraphQL 的选项。

Option描述
mutations除 Payload 提供的默认 Mutation 外，可以添加任何自定义 Mutation。了解更多
queries除 Payload 提供的默认 Query 外，可以添加任何自定义 Query。了解更多
maxComplexity用于设置请求允许的最大复杂度的数值。了解更多
disablePlaygroundInProduction布尔值，如果设为 false 将启用 GraphQL playground，默认为 true。了解更多
disable布尔值，如果设为 true 将完全禁用 GraphQL，默认为 false。
validationRules接收 ExecutionArgs 并返回 ValidationRules 数组的函数。

集合 (Collections)

通过 REST 或 Local API 能对集合执行的所有操作，都可以通过 GraphQL 实现（除了上传文件，这仅支持 REST）。如果你有如下集合配置：

import type { CollectionConfig } from 'payload'

export const PublicUser: CollectionConfig = {
  slug: 'public-users',
  auth: true, // 启用了认证
  fields: [
    ...
  ],
}

Payload 会自动开放以下查询：

查询名称操作类型
PublicUserfindByID
PublicUsersfind
countPublicUserscount
mePublicUserme 认证操作

以及以下变更操作：

查询名称操作类型
createPublicUsercreate
updatePublicUserupdate
deletePublicUserdelete
forgotPasswordPublicUserforgotPassword 认证操作
resetPasswordPublicUserresetPassword 认证操作
unlockPublicUserunlock 认证操作
verifyPublicUserverify 认证操作
loginPublicUserlogin 认证操作
logoutPublicUserlogout 认证操作
refreshTokenPublicUserrefresh 认证操作

全局数据 (Globals)

全局数据也得到完整支持。例如：

import type { GlobalConfig } from 'payload';

const Header: GlobalConfig = {
  slug: 'header',
  fields: [
    ...
  ],
}

Payload 会开放以下查询：

查询名称操作类型
HeaderfindOne

以及以下变更操作：

查询名称操作类型
updateHeaderupdate

用户偏好设置

Admin Panel 中的用户偏好设置也可以通过 GraphQL 访问，其生成方式与其他 collection schema 相同。查询偏好设置时，必须在请求头中提供授权令牌，且只能访问该用户的偏好设置。

Payload 将开放以下查询：

Query NameOperation
PreferencefindOne

以及以下变更操作：

Query NameOperation
updatePreferenceupdate
deletePreferencedelete

GraphQL Playground

GraphQL Playground 在开发环境中默认启用，但在生产环境中默认禁用。你可以在主 Payload Config 中将 graphQL.disablePlaygroundInProduction 设置为 false 来在生产环境中启用它。

你甚至可以使用 login[collection-singular-label-here] 变更操作登录，以认证用户的身份使用 Playground。

提示：

要了解更多关于上述查询和变更操作的使用方法，请在服务器运行时访问你的 GraphQL playground (默认地址为 ${SERVER_URL}/api/graphql-playground)。 在那里，你可以使用右侧的 "Schema" 和 "Docs" 按钮查看关于 Payload 中 GraphQL 操作的详细说明。

自定义验证规则

你可以通过在 Payload Config 中定义 validationRules 函数来为 GraphQL API 添加自定义验证规则。该函数应返回一个 Validation Rules 数组，这些规则将应用于所有传入的查询和变更操作。

import { GraphQL } from '@payloadcms/graphql/types'
import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  graphQL: {
    validationRules: (args) => [NoProductionIntrospection],
  },
  // ...
})

const NoProductionIntrospection: GraphQL.ValidationRule = (context) => ({
  Field(node) {
    if (process.env.NODE_ENV === 'production') {
      if (node.name.value === '__schema' || node.name.value === '__type') {
        context.reportError(
          new GraphQL.GraphQLError(
            'GraphQL introspection is not allowed, but the query contained __schema or __type',
            { nodes: [node] },
          ),
        )
      }
    }
  },
})

查询复杂度限制

Payload 内置了查询复杂度限制器，防止恶意用户通过运行大规模查询来拖慢服务器。了解更多信息，请点击这里。

字段复杂度

你可以为 relationship、upload 和 join 类型的字段定义自定义复杂度。这对于那些解析成本较高的字段特别有用，可以为它们分配更高的复杂度值。这有助于防止用户运行过于复杂的查询。

const fieldWithComplexity = {
  name: 'authors',
  type: 'relationship',
  relationship: 'authors',
  graphQL: {
    complexity: 100, // highlight-line
  },
}