Payload 核心概念

Payload 围绕一组简洁直观的高级概念构建。在开始使用 Payload 之前，熟悉这些概念有助于建立讨论 Payload 时的共同语言和理解基础。

配置 (Config)

Payload Config 是 Payload 所有功能的核心。它通过简单直观的 API 实现对应用程序的深度配置。Payload Config 是一个完全类型化的 JavaScript 对象，可以无限扩展。更多详情

数据库 (Database)

Payload 是数据库无关的，这意味着你可以通过所谓的数据库适配器 (Database Adapter)，在 Payload 熟悉的 API 背后使用任何类型的数据库。更多详情

集合 (Collections)

Collection 是一组共享相同模式的记录（称为 Documents）。每个 Collection 根据你定义的 Fields 存储在 Database 中。更多详情

全局数据 (Globals)

Global 在很多方面类似于 Collections，但它只对应单个 Document。每个 Global 根据你定义的 Fields 存储在 Database 中。更多详情

字段 (Fields)

Field 是 Payload 的构建模块。它们定义了将存储在 Database 中的 Documents 的模式，并自动在 Admin Panel 中生成相应的 UI。更多详情

钩子 (Hooks)

Hook 允许你在 Document 生命周期的特定事件（如读取前、创建后等）中执行自己的副作用。更多详情

认证

Payload 提供了一种安全、可移植的方式来开箱即用地管理用户账户。Payload 认证系统设计用于 Admin Panel 和你自己的外部应用程序。更多详情。

访问控制

访问控制决定了用户对任何给定文档可以执行和不能执行的操作（如读取、更新等），以及他们在 Admin Panel 中可以看到和不能看到的内容。更多详情。

管理面板

Payload 动态生成一个美观、完全类型安全的界面来管理你的用户和数据。Admin Panel 是一个使用 Next.js App Router 构建的 React 应用程序。更多详情。

数据检索

Payload 的所有功能（创建、读取、更新、删除、登录、登出等）都通过三种 API 提供给你：

• 本地 API - 极快的直接数据库访问
• REST API - 用于查询和变更数据的标准 HTTP 端点
• GraphQL API - 完整的 GraphQL API 及 GraphQL Playground

本地 API (Local API)

Payload 最强大的特性之一就是它通过 Local API 让你能够直接访问数据库数据。这种方式极其高效，不会产生任何典型的 HTTP 开销——你直接在 Node.js 中查询数据库。

Local API 采用 TypeScript 编写，因此具有强类型特性，使用体验极佳。它可以在服务器端的任何地方使用，包括自定义 Next.js 路由、Payload 钩子、Payload 访问控制以及 React 服务器组件。

以下是一个使用 Local API 获取数据的 React 服务器组件示例：

import React from 'react'
import config from '@payload-config'
import { getPayload } from 'payload'

const MyServerComponent: React.FC = () => {
  const payload = await getPayload({ config })

  // 这里的 `findResult` 会被完全类型化为 `PaginatedDocs<Page>`，
  // 包含返回的 `docs` 以及关于返回/可用项目总数的信息等
  const findResult = await payload.find({ collection: 'pages' })

  return (
    <ul>
      {findResult.docs.map((page) => {
        // 在这里渲染任何内容！
        // `page` 会被完全类型化为你的 Pages collection！
      })}
    </ul>
  )
}

REST API

默认情况下，Payload 的 REST API 会自动挂载到你应用的 /api 路径下。

例如，如果你有一个名为 pages 的 Collection：

fetch('https://localhost:3000/api/pages') // highlight-line
  .then((res) => res.json())
  .then((data) => console.log(data))

GraphQL API

Payload 会自动通过专用的 GraphQL API 暴露 GraphQL 查询和变更操作。默认情况下，GraphQL 路由处理器会被挂载到应用的 /api/graphql 路径下。你还可以在应用的 /api/graphql-playground 路径下访问完整的 GraphQL Playground。

你可以使用任何 GraphQL 客户端来连接 Payload 的 GraphQL 端点。以下是几个推荐的包：

• graphql-request - 一个非常轻量级的 GraphQL 客户端
• @apollo/client - 行业标准的 GraphQL 客户端，提供许多优秀特性

包结构

Payload 被抽象为一组专用包，以尽可能保持核心 payload 包的轻量化。这样你可以根据项目需求只安装 Payload 的特定部分。

payload

payload 包包含 Payload 的核心业务逻辑。你可以将 Payload 视为一个拥有超能力的 ORM —— 它包含了所有 Payload "操作" 的逻辑，如 find、create、update 和 delete，并暴露了 Local API。它执行 访问控制、钩子、验证 等功能。

Payload 本身极其精简，可以在任何 Node 环境中使用。只要安装了 payload 并能访问 Payload 配置，你就可以直接查询和修改数据库，无需经过不必要的 HTTP 层。

Payload 还包含所有 TypeScript 定义，可以直接从 payload 导入。

以下是导入常见 Payload 类型的方式：

import { Config, CollectionConfig, GlobalConfig, Field } from 'payload'

@payloadcms/next

Payload 本身负责直接数据库访问和控制业务逻辑，而 @payloadcms/next 包则负责管理 Admin 面板和 Payload 暴露的整个 HTTP 层，包括 REST API 和 GraphQL API。

@payloadcms/graphql

Payload 的所有 GraphQL 功能都被抽象到单独的包中。Payload 本身、其 Admin UI 和 REST API 与 GraphQL 完全没有重叠，如果不使用 GraphQL，你将不会产生任何性能开销。不过它被内置在 @payloadcms/next 包中，因此无需手动安装。但如果使用 GraphQL，你需要在 package.json 中单独安装 GraphQL。

@payloadcms/ui

这是 Payload Admin 面板使用的 UI 库。所有组件都从这个包导出，可以在扩展 Payload 管理界面时重用，或者在你自己的 React 应用中使用 Payload 组件。部分导出是服务端组件，部分是客户端组件。

@payloadcms/db-postgres、@payloadcms/db-vercel-postgres、@payloadcms/db-mongodb、@payloadcms/db-sqlite

你可以为项目选择所需的数据库适配器，无论选择哪个，Payload 的整个数据层都包含在这些包中。每个项目同一时间只能使用一个适配器。

@payloadcms/richtext-lexical、@payloadcms/richtext-slate

Payload 的富文本功能被抽象到单独的包中。如果要在项目中启用富文本，需要安装其中一个包。我们推荐新项目使用 Lexical，这是 Payload 未来重点发展的方向，但如果你已经基于 Slate 构建，它仍然受支持。