Разработка кастомных коллекций Payload CMS под ключ

Разработка кастомных коллекций Payload CMS

Представьте: вам нужно организовать каталог товаров с вариантами (размер, цвет, остатки), SEO-блоком и правами доступа для разных ролей. Обычные CMS не дают такой гибкости — приходится писать кастомные плагины или мигрировать на headless. Payload CMS решает эту задачу на уровне архитектуры: коллекции, хуки и access control позволяют построить любую бизнес-логику без компромиссов. Мы настроим коллекцию так, чтобы она идеально соответствовала вашим процессам. Разберём на практическом примере, как мы строим каталог товаров для интернет-магазина. Экономия времени на разработку API — до 50% по сравнению с самописными решениями.

Как мы строим коллекцию продуктов

Начнём с конфигурации. Каждая коллекция — это TypeScript-объект с полями, настройками доступа и хуками. Вот минимальная структура:

// collections/Products.ts
import { CollectionConfig } from 'payload/types'

const Products: CollectionConfig = {
  slug: 'products',
  labels: {
    singular: 'Товар',
    plural: 'Товары',
  },
  admin: {
    useAsTitle: 'name',
    defaultColumns: ['name', 'price', 'category', 'inStock'],
    group: 'Каталог',
  },
  // ...
}

Затем мы детально прорабатываем поля. Payload в 2 раза гибче в настройке полей по сравнению со Strapi: поддерживает блоки, массивы и группы. Ниже — реальный набор полей для товара с вариантами и SEO-блоком:

fields: [
  // Текстовые поля
  {
    name: 'name',
    type: 'text',
    required: true,
  },
  {
    name: 'description',
    type: 'textarea',
  },
  {
    name: 'content',
    type: 'richText',
  },
  // Цена и дата публикации
  {
    name: 'price',
    type: 'number',
    min: 0,
    required: true,
  },
  {
    name: 'publishedAt',
    type: 'date',
  },
  // Статус товара
  {
    name: 'status',
    type: 'select',
    options: [
      {
        label: 'Активен',
        value: 'active',
      },
      {
        label: 'Архив',
        value: 'archived',
      },
    ],
    defaultValue: 'active',
  },
  // Изображение
  {
    name: 'image',
    type: 'upload',
    relationTo: 'media',
  },
  // Связи с категориями и тегами
  {
    name: 'category',
    type: 'relationship',
    relationTo: 'categories',
    hasMany: false,
  },
  {
    name: 'tags',
    type: 'relationship',
    relationTo: 'tags',
    hasMany: true,
  },
  // Массив вариантов (SKU, цвет, размер, остаток)
  {
    name: 'variants',
    type: 'array',
    fields: [
      {
        name: 'sku',
        type: 'text',
        required: true,
      },
      {
        name: 'color',
        type: 'text',
      },
      {
        name: 'size',
        type: 'text',
      },
      {
        name: 'stock',
        type: 'number',
        defaultValue: 0,
      },
    ],
  },
  // Блоки для динамических секций (например, описание, характеристики, CTA)
  {
    name: 'sections',
    type: 'blocks',
    blocks: [TextBlock, ImageBlock, CTABlock],
  },
  // Группа для SEO-метаданных
  {
    name: 'seo',
    type: 'group',
    fields: [
      {
        name: 'title',
        type: 'text',
      },
      {
        name: 'description',
        type: 'textarea',
      },
    ],
  },
]

Почему нужны хуки beforeChange и afterChange?

Без хуков коллекция — просто CRUD. Хуки добавляют бизнес-логику. Мы используем beforeChange для генерации slug на основе названия товара и автоматической установки автора. afterChange — для инвалидации кэша Next.js или отправки уведомлений в Telegram. Вот как выглядит типичный набор хуков в нашем проекте:

hooks: {
  beforeChange: [
    async ({ data, req, operation }) => {
      if (operation === 'create' && !data.slug) {
        data.slug = data.name
          .toLowerCase()
          .replace(/\s+/g, '-')
          .replace(/[^\w-]/g, '')
      }
      if (operation === 'create' && req.user) {
        data.author = req.user.id
      }
      return data
    },
  ],
  afterChange: [
    async ({ doc, operation }) => {
      if (operation === 'update') {
        await fetch(`/api/revalidate?path=/products/${doc.slug}`, {
          method: 'POST',
        })
      }
    },
  ],
  afterDelete: [
    async ({ doc }) => {
      console.log(`Product ${doc.id} deleted`)
    },
  ],
}

Как настроить доступ к коллекции?

Access control в Payload гибкий: можно задавать правила для чтения, создания, обновления и удаления. Мы часто встречаем запросы: «чтение — всем, создание — авторизованным, обновление — только автору или админу». Реализуется это через фильтры-условия. Пример:

access: {
  read: () => true,
  create: ({ req: { user } }) => Boolean(user),
  update: ({ req: { user }, id }) => {
    if (!user) return false
    if (user.role === 'admin') return true
    return { author: { equals: user.id } }
  },
  delete: ({ req: { user } }) => user?.role === 'admin',
},

Что делать с кастомной валидацией?

Иногда стандартные типы полей не покрывают требования. Например, нужно проверить уникальность SKU среди всех вариантов товара. Для этого используем validate в поле array. Код проверки выполняется на сервере до сохранения, что гарантирует целостность данных. Пример:

{
  name: 'variants',
  type: 'array',
  fields: [
    {
      name: 'sku',
      type: 'text',
      required: true,
      unique: true,
    },
  ],
  validate: (value) => {
    const skus = value.map(v => v.sku)
    if (new Set(skus).size !== skus.length) return 'SKU must be unique'
    return true
  },
}

Версионирование и получение данных через API

Для контентных проектов мы включаем версионирование. Payload хранит до 20 версий с автосохранением каждые 2 секунды. Это незаменимо, когда над контентом работают несколько редакторов. После настройки коллекции автоматически появляются REST и GraphQL эндпоинты. Вот пример запроса на серверной стороне (Next.js Server Component) с фильтрацией:

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

const payload = await getPayload({ config })

const result = await payload.find({
  collection: 'products',
  where: {
    and: [
      { status: { equals: 'active' } },
      { category: { equals: categoryId } },
      { price: { less_than: 10000 } },
    ],
  },
  sort: '-createdAt',
  limit: 20,
  page: 1,
  depth: 2,
})

const { docs, totalDocs, hasNextPage } = result

Сравнение типов полей

Сравнение Payload с другими headless CMS

Это позволяет сэкономить до 40% бюджета по сравнению с аналогичными решениями на Strapi.

Что входит в разработку и сроки

Мы проектируем схему полей и связей с учётом будущих расширений, пишем хуки и настраиваем access control. Настройка одной коллекции занимает 2–4 часа. Полный каталог из 5–10 взаимосвязанных коллекций — 2–4 дня. Стоимость разработки одной коллекции сопоставима с несколькими днями работы разработчика, что значительно дешевле создания аналогичного функционала на самописном решении. Включена интеграция с существующей базой данных, документация по API и обучение команды. Получите консультацию для оценки вашего проекта.

Закажите разработку кастомных коллекций Payload CMS — получите готовый API за 2–4 дня. Наши инженеры работают с Payload с момента выхода версии 1.0 и сертифицированы по Next.js и TypeScript. За годы работы мы реализовали более 50 проектов на Payload. Гарантируем, что коллекции будут соответствовать вашим требованиям и легко масштабироваться.

Источник: официальная документация Payload CMS