Каталог услуг на Directus: меняем цены в панели и получаем данные через API

MAATRIX · 17 октября 2026 · 8 мин чтения

В небольшом каталоге самая трудная операция иногда выглядит так: поменять число с 4500 на 4900. Менеджер пишет разработчику, разработчик ищет значение в коде, сайт собирается заново, а на другой странице остаётся старая цена. После третьего такого случая хочется вынести содержимое сайта туда, где его можно редактировать без выпуска приложения.

Directus даёт панель управления данными и API. Сотрудник меняет карточку услуги, а сайт получает согласованный набор полей. Важно заранее отделить публикацию от черновика, внутреннюю себестоимость от цены для клиента и редактирование каталога от полного управления сервером.

Соберём учебный каталог сервисной компании. В нём есть название, краткое описание, цена, порядок вывода и статус публикации. Это небольшой проект, на котором удобно проверить устройство headless CMS до переноса настоящего сайта.

Начните с модели одной услуги

Создайте коллекцию services. У записи будет уникальный ID и следующие поля:

Хранение цены целым числом помогает избежать ошибок двоичной дробной арифметики. Например, значение 490000 при двух знаках после разделителя означает 4900 рублей. Правило преобразования должно быть единым для панели, сайта и выгрузок.

Если услуга продаётся «от указанной суммы», добавьте отдельное логическое поле. Не прячьте слово «от» внутрь числового значения. Если цена зависит от длительности или варианта исполнения, лучше завести связанную таблицу вариантов, чем десять колонок с названиями «цена2» и «цена_новая».

Механика создания коллекций описана в документации Directus. Сначала создайте несколько учебных записей: опубликованную услугу, черновик и услугу без цены. Последняя поможет проверить поведение интерфейса в неполном состоянии.

Установка и условия использования

Перед развёртыванием прочитайте лицензию выбранного выпуска Directus. Условия самостоятельного размещения и коммерческого использования нужно оценивать для своей организации. Не закладывайте в бюджет предположение «исходный код открыт, значит любые условия бесплатны».

Для небольшого каталога можно начать пилот на MAATRIX Uab Start: 2 vCPU и 4 GB памяти. Если на том же VPS собирается тяжёлое веб-приложение, обрабатываются изображения и работает база, Heka Standard с 8 GB памяти даст больше пространства для проверки. Это ориентиры для старта; реальную нагрузку определяют запросы, объём файлов и способ кеширования сайта.

Разместите Directus на поддерживаемой Linux-системе, например Ubuntu 24.04, используя проверенный выпуск и официальный способ установки. Базовую процедуру можно сверить с руководством MAATRIX. Назначьте панели отдельный адрес, включите HTTPS, храните файлы в постоянном томе и закройте порт базы снаружи.

Демонстрационный SQLite удобен для знакомства, но решение о рабочей базе принимайте с учётом резервного копирования, конкурирующих операций и эксплуатации. Не меняйте СУБД в день запуска без пробного переноса.

Редактор видит каталог, посетитель — опубликованную часть

Создайте роль редактора каталога. Дайте ей чтение и изменение нужных полей services, но не административный доступ ко всем настройкам. Если сотрудник должен создавать записи, включите создание; удаление лучше оставить ограниченным, пока команда не согласовала порядок архивации.

Для публичного чтения настройте отдельные разрешения: только действие read, только статус published и только поля, которые нужны посетителю. Внутренние комментарии, закупочная стоимость и служебные контакты не должны уходить в публичный API.

Права Directus задаются через политики, а разрешения нескольких политик складываются. Это важно: дополнительная широкая политика может открыть то, что вы аккуратно ограничили в другой. Устройство правил описано в руководстве Access Control.

Проверяйте настройки отдельным запросом без авторизации. Вход администратора в соседней вкладке иногда создаёт приятную иллюзию, что публичная часть уже работает. Затем откройте черновик по известному ID: отсутствие карточки в общем списке ещё не доказывает, что прямая выдача закрыта.

Получаем данные для сайта

Для публичного каталога не нужен административный токен в JavaScript. Если чтение разрешено гостю, сайт обращается к публичному API. Если проект использует серверное получение закрытых данных, токен хранится только на сервере и имеет минимальные права.

Вот проверочный запрос к учебному домену. Замените адрес своим, названия полей должны соответствовать созданной коллекции:

curl --fail --get 'https://cms.example.com/items/services' \
  --data-urlencode 'fields=id,title,slug,summary,price_minor,currency,sort' \
  --data-urlencode 'filter[status][_eq]=published' \
  --data-urlencode 'sort=sort,title' \
  --data-urlencode 'limit=50'

Фильтр в запросе полезен, но защиту обеспечивает правило на сервере. Посетитель может изменить параметры URL, поэтому публичная политика сама должна запрещать чтение черновиков. Подробности операций с записями есть в API Directus.

В ответе проверьте структуру, тип цены и отсутствие лишних полей. Для большого каталога реализуйте пагинацию. Нельзя считать первые пятьдесят записей полным списком только потому, что демонстрационных услуг было четыре.

На стороне сайта обрабатывайте недоступность API. Предусмотрите понятное сообщение или последнюю корректную кешированную версию. Пустой массив из-за ошибки соединения не должен превращаться в сообщение «мы больше не оказываем услуг».

Почему цена в панели изменилась, а на сайте — нет

Между сохранением записи и экраном посетителя могут стоять кеш Directus, серверный кеш приложения, статическая сборка и CDN. Каждый уровень имеет свой срок жизни. Поэтому определите допустимую задержку обновления заранее.

Для маленького каталога можно получать данные на сервере с коротким кешем. Для статического сайта — запускать сборку по событию публикации и проверять её результат. Если используется webhook, он должен быть защищён, а повторная доставка не должна порождать бесконечную очередь одинаковых сборок.

Проверка проста: поменяйте цену учебной услуги, запишите время и откройте сайт в чистой сессии. Сравните панель, ответ API и страницу. Так вы найдёте конкретный уровень задержки, вместо того чтобы по очереди очищать все кеши в надежде на чудо.

Если цены участвуют в оформлении заказа, окончательную сумму считайте на сервере заказа по актуальным правилам. Значение, присланное браузером, нельзя принимать как достоверную стоимость. Каталог показывает предложение, а платёжный процесс проверяет его применимость.

Ошибки редактора тоже входят в проект

Добавьте ограничения на обязательные поля, допустимые статусы и диапазон цены. Проверьте, что отрицательная сумма и пустое название не проходят в публикацию. Для slug нужна уникальность и согласованная политика изменения адресов.

Не позволяйте редактору случайно вставить в краткое описание произвольный HTML, если фронтенд ждёт обычный текст. Для форматированного содержимого выбирайте подходящее поле и безопасный способ отображения. Удобство копирования из документа не должно превращаться в исполнение чужого кода в браузере клиента.

Сделайте понятный порядок работы: создать черновик, заполнить карточку, посмотреть предварительный результат, опубликовать. Для сложного согласования проверьте возможности текущей версии и спроектируйте роли. Не называйте простое поле status полноценным процессом утверждения, если любой редактор может менять его без проверки.

Полезно провести небольшое обучение на тестовой базе. Пусть сотрудник сам добавит услугу, изменит цену и обнаружит ошибку до публикации. Пять минут практики заменяют длинную инструкцию, которую никто не откроет в пятницу вечером.

Изменение цены должно иметь дату

Для обычного справочного каталога достаточно текущего значения. Если компания готовит предложения заранее, полезно отделить действующую цену от запланированной. Не заставляйте менеджера ставить будильник на полночь, чтобы вручную заменить сумму в панели.

Спроектируйте отдельные записи цен с датой начала действия или согласованный процесс публикации новой версии. Уточните часовой пояс и поведение на границе суток. Проверяйте этот сценарий на тестовых данных: последняя минута старого периода и первая минута нового должны давать ожидаемые значения.

Не удаляйте прежнюю стоимость из уже созданного заказа. Заказ должен хранить свои согласованные суммы, а каталог — актуальное предложение для следующей покупки. Связь по ID услуги помогает найти источник, но не должна автоматически переписывать историю расчётов.

Для ручных изменений заведите короткое правило: кто запросил, кто проверил и когда опубликовали. Если используются журналы активности Directus, проверьте состав записей и срок их хранения в своей версии. Само наличие раздела истории не освобождает от резервного копирования.

Перед массовой правкой сделайте выгрузку изменяемых записей. Сначала примените изменение к небольшой тестовой группе и сравните итоговые ответы API. Ошибка в единицах цены, умноженная на весь каталог, выглядит гораздо убедительнее, чем хотелось бы.

Сохраняем не только контейнер

Резервная копия включает базу, загруженные файлы, конфигурацию и необходимые секреты. Отдельно храните описание схемы и зафиксированные версии. Перед обновлением проверьте копию системы и несколько запросов, которыми пользуется сайт.

Для отката нужны совместимые данные: прежний образ может не понять базу после миграции. Согласуйте окно изменения и способ вернуть предыдущую согласованную копию. Если каталог обновляется во время работ, отдельно учитывайте новые записи и правки.

Готовность проекта проверяется короткой цепочкой: редактор меняет карточку, гостевой API возвращает только разрешённые данные, сайт показывает результат за известное время, а ошибку можно исправить и проследить. После этого изменение цены перестаёт быть задачей программиста — и у него наконец появляется шанс заняться той самой кнопкой, которую все давно просили перенести.