开始 - 概念 - 《Payload 开发文档 - 帮助手册 - 教程》

配置（Config）
数据库（Database）
集合（Collections）
全局（Globals）
字段（Fields）
钩子（Hooks）
认证（Authentication）
访问控制（Access Control）
管理面板（Admin Panel）
检索数据
包结构

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

配置（Config）

Payload 配置是 Payload 所做的一切的核心。它允许您通过简单直观的 API 深入配置您的应用程序。Payload 配置是一个完全类型的 JavaScript 对象，可以无限扩展。更多细节。

数据库（Database）

Payload 对数据库不敏感，这意味着您可以通过所谓的数据库适配器在 Payload 的熟悉 API 后使用任何类型的数据库。更多细节。

集合（Collections）

集合是一组记录，称为文档，它们都共享一个共同的模式。每个集合都根据您的定义存储在数据库中，基于您定义的字段。更多细节。

全局（Globals）

全局在很多方面与集合相似，但它们只对应一个文档。每个全局都根据您的定义存储在数据库中，基于您定义的字段。更多细节。

字段（Fields）

字段是 Payload 的构建块。它们定义了将存储在数据库中的文档的模式，并且自动生成管理面板中相应的 UI。更多细节。

钩子（Hooks）

钩子允许您在文档生命周期的特定事件中执行自己的副作用，例如在读取之前、创建之后等。更多细节。

认证（Authentication）

Payload 提供了一种安全、便携的方式来管理用户账户。Payload 认证旨在在管理面板以及您自己的外部应用程序中使用。更多细节。

访问控制（Access Control）

访问控制决定了用户可以和不可以对任何给定的文档做什么，例如读取、更新等，以及他们在管理面板中可以和不可以看到什么。更多细节。

管理面板（Admin Panel）

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

检索数据

Payload 所做的一切（创建、读取、更新、删除、登录、注销等）都通过三个 API 暴露给您：

本地 API - 极快的直接数据库访问
REST API - 用于查询和修改数据的标准 HTTP 端点
GraphQL - 一个完整的 GraphQL API 以及一个 GraphQL Playground

注意： 所有这些 API 共享完全相同的查询语言。更多细节。

本地 API

Payload 最强大的方面之一是它通过本地 API为您提供直接数据库访问。它非常快，不会产生任何典型的 HTTP 开销 - 您可以直接在 Node.js 中查询数据库。

本地 API 用 TypeScript 编写，因此它是强类型的，非常好用。它在服务器上的任何地方都可以工作，包括自定义 Next.js 路由、Payload 钩子、Payload 访问控制和 React 服务器组件。

以下是使用本地 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` 是完全类型化的，作为您的页面集合！
      })}
    </ul>
  );
};
export default MyServerComponent;

有关本地 API 的更多信息，请点击这里。

REST API

默认情况下，Payload 的REST API会自动为您安装在应用的 /api 路径上。

例如，如果您有一个名为 pages 的集合：

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

有关 REST API 的更多信息，请点击这里。

GraphQL API

Payload 通过专用的GraphQL API自动公开 GraphQL 查询和突变。默认情况下，GraphQL 路由处理器安装在应用的 /api/graphql 路径上。您还会发现一个完整的 GraphQL Playground，可以在应用的 /api/graphql-playground 路径上访问。

您可以使用任何 GraphQL 客户端与 Payload 的 GraphQL 端点一起使用。以下是一些软件包：

graphql-request - 一个非常轻量的 GraphQL 客户端
@apollo/client - 一个具有许多不错功能的行业标准 GraphQL 客户端

有关 GraphQL API 的更多信息，请点击这里。

包结构

Payload 被抽象成一组专用的包，以保持核心 payload 包尽可能轻量。这允许您根据您的独特项目需求仅安装 Payload 的部分。

重要： 所有官方 Payload 包的版本号始终同步发布。您应该确保始终使用所有官方 Payload 包的匹配版本。

payload

payload 包是 Payload 核心业务逻辑所在。您可以将 Payload 视为具有超能力的 ORM - 它包含所有 Payload “操作”的逻辑，如 find、create、update 和 delete，并暴露一个本地 API。它执行访问控制、钩子、验证等。

Payload 本身非常紧凑，可以在任何 Node 环境中使用。只要您安装了 payload 并且可以访问您的 Payload 配置，您就可以直接查询和修改数据库，而无需通过不必要的 HTTP 层。

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

以下是如何导入一些常见的 Payload 类型：

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

@payloadcms/next

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

@payloadcms/graphql

Payload 的所有 GraphQL 功能都被抽象成一个单独的包。Payload、其管理 UI 和 REST API 与 GraphQL 完全没有重叠，如果您不使用 GraphQL，您将不会从 GraphQL 那里遭受任何性能开销。但是，它被安装在 @payloadcms/next 包内，所以您不需要手动安装它。然而，如果您使用 GraphQL，您需要在 package.json 中单独安装 GraphQL。

@payloadcms/ui

这是 Payload 管理面板使用的 UI 库。所有组件都从这个包中导出，可以在您构建 Payload 管理 UI 的扩展时重用，或者在您自己的 React 应用中使用 Payload 组件。一些导出是服务器组件，一些是客户端组件。

@payloadcms/db-postgres, @payloadcms/db-vercel-postgres, @payloadcms/db-mongodb

您可以选择为您的项目使用哪个数据库适配器，无论您选择哪个，Payload 的整个数据层都包含在这些包中。您一次只能为任何给定项目使用一个。

@payloadcms/richtext-lexical, @payloadcms/richtext-slate

Payload 的富文本功能被抽象成单独的包，如果您想在项目中启用富文本，您需要安装这些包中的一个。我们建议所有新项目使用 Lexical，这是 Payload 从这一点开始将集中努力的地方，但 Slate 仍然受到支持，如果您已经使用它构建。

注意： 富文本完全是可选的，您可能不需要它来完成您的项目。