钩子概述

钩子（Hooks）允许你在文档生命周期的特定事件中执行自定义的副作用操作。通过钩子，你可以在应用程序的精确时刻实现数据变更、执行业务逻辑、与第三方集成等功能。

借助钩子，你可以将 Payload 从传统 CMS 转变为完整的应用框架。钩子的常见使用场景包括：

  • 在数据读取或更新前进行修改
  • 加密和解密敏感数据
  • 与 HubSpot 或 Salesforce 等第三方 CRM 集成
  • 将上传的文件副本发送到 Amazon S3 等存储服务
  • 通过 Stripe 等支付提供商处理订单
  • 提交联系表单时发送邮件
  • 跟踪数据所有权或变更历史

Payload 提供四种主要类型的钩子：

提醒： Payload 还提供了一组用于前端应用的 React 钩子。虽然名称相似，但它们是完全不同的概念，请注意区分。了解更多。

根钩子

根钩子不与任何特定集合、全局或字段关联，适用于应用级别的全局副作用操作，例如当应用发生错误时。

要在 Payload 配置 中添加根钩子，使用 hooks 属性：

import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  // highlight-start
  hooks: {
    afterError:[() => {...}]
  },
  // highlight-end
})

可用选项如下：

选项描述
afterError在 Payload 应用发生错误后执行。

afterError

afterError Hook 在 Payload 应用程序发生错误时触发。这个钩子可用于将错误记录到第三方服务、发送邮件给开发团队、将错误记录到 Sentry 或 DataDog 等场景。其输出可用于转换结果对象/状态码。

import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  hooks: {
    afterError: [
      async ({ error }) => {
        // 执行某些操作
      },
    ],
  },
})

afterError Hook 提供以下参数：

参数描述
error发生的错误对象。
context在 Hooks 之间传递的自定义上下文。查看更多详情。
graphqlResultGraphQL 结果对象，如果该钩子在 GraphQL 上下文中执行则可用。
req扩展自 Web Request 的 PayloadRequest 对象。包含当前认证的 user 和 Local API 实例 payload。
collection该 Hook 运行所针对的 Collection。如果钩子从非 collection 端点或 GraphQL 执行，则为 undefined。
result格式化的错误结果对象，如果该钩子从 REST 上下文执行则可用。

异步 vs. 同步

所有 Hook 都可以写成同步或异步函数。选择哪种类型取决于你的使用场景，但两者之间的切换非常简单，只需添加或移除 async 关键字即可。

异步方式

如果 Hook 需要在文档更新或创建前修改数据，并且依赖于异步操作（如从第三方获取数据），那么将 Hook 定义为异步函数可能更合适。这样可以确保 Hook 在操作生命周期继续之前完成。异步 Hook 是按顺序运行的——如果你定义了两个异步 Hook，第二个 Hook 会等待第一个完成后才开始执行。

同步方式

如果你的 Hook 只是执行一些副作用操作（如更新 CRM），那么可以将其定义为同步函数，这样 Payload 操作就不必等待 Hook 完成。

仅服务器端执行

Hook 仅在服务器端触发，并自动从客户端包中排除。这意味着你可以在 Hook 中安全地使用敏感的业务逻辑，而不用担心将其暴露给客户端。