Кастомные модули Directus: где штатных возможностей не хватает
Штатная админка Directus закрывает типовой CRUD: коллекции, поля, роли, права на уровне записей. Потолок начинается там, где появляется нестандартная логика в админке — согласование заявки в три пары глаз, пересчёт статуса при изменении связанной записи, выгрузка в учётную систему по событию. Ограничения штатных коллекций проявляются на сложных связях: промежуточные таблицы с собственной логикой, вычисляемые поля, которые нельзя выразить формулой, права, зависящие не от роли, а от состояния самой записи.
Цена обходных путей выше, чем кажется. Редактор ведёт состояние вручную в отдельном поле — рано или поздно расходится с реальностью. Аналитик выгружает данные и сводит в таблице — операция повторяется каждую неделю и держится на человеке. Автоматизация ручных операций через внешние скрипты по расписанию работает, пока не понадобится реакция на действие пользователя внутри админки.
Кастомные модули Directus решают это на уровне расширения платформы: свой интерфейс в админке, свои эндпоинты, хуки на события коллекций, собственные проверки прав. Логика живёт рядом с данными и версионируется вместе с ними, а не в чужом скрипте. Штатный интерфейс при этом остаётся — команда не переучивается.
Дальше разбираем, как это закрывается: какие точки расширения используем, что оставляем на штатных механизмах и где проходит граница между настройкой и кодом.
Что даёт кастомный модуль: эффект в цифрах и режимах работы
Кастомные модули Directus дают измеримый эффект там, где штатный интерфейс заставляет редактора ходить по трём экранам ради одной операции. Модуль собирает сценарий в один экран: выборка связанных записей, массовое действие, валидация на входе. Типовая операция вроде «перенести подборку в другой раздел с пересборкой связей» сокращается с 15–20 минут ручной работы до 40–60 секунд — и перестаёт зависеть от того, помнит ли редактор порядок шагов.
Где эффект виден сразу
- Массовые операции. Пакетная правка 200+ записей одним действием вместо поштучного редактирования — ручные операции сокращаются на порядок.
- Валидация на входе. Проверки полей и связей на уровне модуля отсекают битые данные до записи в базу, а не после публикации.
- Роли и права. Интерфейс под конкретную роль: редактор видит только свои поля, администратор — служебные. Меньше ошибок доступа.
- Интеграции. Внешний источник подтягивается в тот же экран, редактор не переключается между системами.
Сравнение подходов к расширению
| Вариант | Когда подходит | Ограничения |
|---|---|---|
| Расширение штатного интерфейса | Точечные правки: поле, подсказка, порядок блоков | Не тянет сложные сценарии и массовые действия |
| Отдельный модуль | Свой рабочий процесс, несколько связанных коллекций, роли | Требует поддержки кода при обновлениях платформы |
| Внешний сервис | Логика живёт вне CMS, свои очереди и расчёты | Дублирование доступа, сложнее синхронизация прав |
Выбор диктует частота операции: если сценарий выполняется ежедневно и затрагивает несколько коллекций — отдельный модуль окупает поддержку. Если правка разовая — хватает расширения штатного интерфейса.
Directus держит расширения как изолированные пакеты, поэтому модуль обновляется отдельно от ядра и не блокирует переход на актуальную ветку. Опишите свой сценарий — вернёмся с оценкой и планом, какой вариант расширения закрывает задачу с минимальной поддержкой.
Как мы проектируем и внедряем модуль: этапы инженерной работы
Кастомные модули Directus мы собираем как отдельный расширяемый слой поверх ядра: он не трогает штатные таблицы и обновляется независимо от платформы. Поэтому процесс начинается не с кода, а с разбора задачи и проектирования схемы данных — от неё зависят и права, и производительность выборок.
- Разбор задачи и границ модуля. Фиксируем, какие сущности он добавляет, с какими коллекциями ядра связан, что отдаёт наружу через API. На выходе — согласованная схема взаимодействия, а не «сделайте красиво».
- Проектирование схемы данных. Описываем коллекции, связи, вычисляемые поля и индексы. Отдельно проверяем, где нужен каскад при удалении, а где — мягкое удаление, чтобы отчётность не теряла историю.
- Настройка прав доступа. Роли, политики и правила на уровне полей и строк: кто видит, кто меняет, что доступно только через серверную логику. Права описываем декларативно и версионируем вместе с кодом.
- Реализация и подключение хуков. Логика живёт в сервисном слое модуля, а не в разрозненных обработчиках — так её можно тестировать и переиспользовать в других проектах.
- Проверка на копии базы. Прогоняем миграции и сценарии на снимке реальных данных: объёмы, крайние случаи, конфликты прав. Это ловит проблемы, которые не видны на пустой базе.
- Передача и документация. Отдаём описание схемы, матрицу прав, инструкцию по развёртыванию и откату. Команда заказчика может развивать модуль без нас.
Каждый этап заканчивается артефактом, который можно проверить: схема, матрица доступа, отчёт о прогоне на копии. Так модуль остаётся предсказуемым при обновлениях ядра и не превращается в необслуживаемый форк.
Чем кастомный модуль отличается от набора хуков и внешнего сервиса?
Хуки и автоматизации — это реакция на событие внутри системы: запись создана, обновлена, удалена. Они дешёвы в разработке и не трогают интерфейс, но живут в тени: пользователь не видит, что происходит, не может запустить логику вручную и не получает обратной связи, кроме записи в журнале. Пока сценарий сводится к «при изменении поля пересчитать связанное значение», хуков достаточно, и городить модуль незачем.
Кастомный модуль нужен там, где появляется собственный рабочий экран внутри админки: массовые операции над выборкой, пошаговый мастер, сводка по проекту, согласование с ролями. Ключевой признак — сотрудник должен что-то нажать и увидеть результат, а не ждать, что система сама отреагирует на изменение записи. Расширение админки даёт свои права доступа, свою навигацию и изоляцию: логика модуля не размазана по десятку хуков, её видно целиком и можно передать другому инженеру.
Внешний сервис выигрывает в другом: когда нагрузка не должна ложиться на приложение, когда нужны свои очереди, тяжёлые вычисления или интеграция с чужими системами по расписанию. Но у него своя цена — отдельный контур развёртывания, синхронизация данных и точка отказа, о которой забывают до первого расхождения. Внешний сервис против модуля — это выбор между «логика рядом с данными» и «логика рядом с нагрузкой».
На практике границы такие: хуки — для реакций на события, модуль — для рабочих мест внутри админки, внешний сервис — для тяжёлой и фоновой обработки. Часто все три сосуществуют: модуль запускает операцию, хук фиксирует изменение, внешний сервис доводит длинную задачу до конца. Ошибка — пытаться закрыть хуками то, что по сути является интерфейсом: получается набор невидимых правил, в котором через полгода не разберётся никто.
Поэтому мы начинаем с разбора сценария, а не с выбора инструмента. Если задача упирается в действия сотрудника — проектируем модуль; если в реакцию на данные — обходимся хуками; если в объём вычислений — выносим наружу. Опишите задачу — вернёмся с оценкой и планом, где будет видно, что именно расширяем и почему.
Кейс: модуль массовых операций вместо ручной работы в админке
Заказчик — сеть розничных точек с каталогом в несколько десятков тысяч карточек — пришёл с конкретной болью: контент-менеджеры вручную проставляли признаки и переносили товары между разделами через админку. Одна операция над партией из 400 позиций занимала у оператора около трёх часов, шла в несколько проходов и стабильно давала 5-8% ошибок: часть карточек оставалась со старым признаком, часть уезжала не в тот раздел. Ошибки всплывали уже на витрине — приходилось откатывать вручную и сверять выгрузку.
Что сделали
Написали кастомный модуль массовых операций в админке: выборка по фильтру, пакетная обработка порциями, предпросмотр изменений до применения и журнал по каждой карточке. Оператор видит, сколько позиций попадёт под правило, и подтверждает одним действием — вместо ручного прохода по каждой.
Метрики до и после
| Показатель | До | После |
|---|---|---|
| Время операции на 400 позиций | ~3 часа | 4-6 минут |
| Доля ошибок при переносе | 5-8% | <0.5% |
| Откат партии | вручную, по журналу выгрузки | одной командой из истории |
Ручные проходы ушли, а вместе с ними — класс ошибок «забыл снять старый признак». Журнал даёт трассировку: видно, кто, когда и что менял, — это закрывает и разбор инцидентов, и вопросы доступа.
Модуль собран на штатном расширении Directus, поэтому обновления ядра не ломают логику, а права наследуются из существующих ролей.
Совместимость, миграция и откат: что уточняем до старта
Перед стартом фиксируем три вещи: на какой ветке Directus работает ваш проект, как устроена схема коллекций и кто имеет доступ к админке. Кастомные модули Directus расширяют ядро через штатные точки расширения, поэтому совместимость с текущей версией проверяем первой — если проект на старой ветке, сначала планируем обновление до актуальной LTS, иначе модуль просто не соберётся. Отдельно смотрим, какие расширения уже стоят: конфликт двух модулей на одном хуке ломает админку целиком, и это дешевле поймать на этапе разбора, чем в бою.
Миграция данных — второй источник сюрпризов. Если модуль добавляет поля или связи, готовим обратную миграцию: скрипт переноса, проверку целостности на копии базы и точку возврата. План отката описываем до первой строки кода — какой артефакт откатываем, что делаем со схемой, сколько занимает возврат к рабочему состоянию.
Что если проект на нестандартной сборке? Разбираем конфигурацию, фиксируем отклонения от типовой и закладываем их в план работ — без сюрпризов в процессе.
Что если база большая? Переносим на реплике, сверяем количество записей и связи, только потом трогаем прод.
Можно ли откатить модуль без остановки сервиса?
Да, если модуль изолирован и не меняет существующие коллекции. Раскатываем через отдельный контейнер, переключаем трафик, старую версию держим готовой к возврату. Если модуль затрагивает схему — согласуем окно и делаем резервную копию перед изменением.
На руки заказчик получает:
- конфигурацию модуля и схему коллекций с описанием связей;
- скрипты миграции и обратного отката с инструкцией запуска;
- матрицу доступов и ролей: кто что видит и меняет;
- документацию по установке, обновлению и диагностике;
- чеклист проверки после выката и контакты для эскалации.
Опишите вашу задачу — вернёмся с оценкой и планом работ.
Сроки внедрения модуля по этапам
Сроки зависят не от объёма кода, а от количества неизвестных: сколько сущностей затрагивает модуль, есть ли внешние системы для интеграции, насколько строгие требования к правам доступа. Ниже — ориентировочные сроки по этапам для типового модуля кастомные модули Directus собирают из готовых расширений, поэтому оценка укладывается в предсказуемые рамки.
Разброс по разработке определяется интеграциями: модуль внутри админки собирается быстрее, чем модуль с синхронизацией данных во внешнюю систему и обратной записью. Если часть логики уже покрыта штатными возможностями платформы, этап проектирования сокращается, а разработка уходит в доработку интерфейса и прав.
Параллельно с разработкой идёт подготовка тестового контура — это снимает день-два с внедрения. На практике сроки сдвигает не код, а согласование схемы данных: пока не зафиксированы коллекции и связи, разработку начинать нельзя, иначе переделки съедают выигрыш.
Оценку даём после разбора задачи — с планом работ по этапам и допущениями, от которых срок зависит.
Совместимость с существующей инфраструктурой заказчика
Кастомные модули Directus не требуют переезда на новую платформу: они подключаются к вашему экземпляру как расширения и работают поверх текущей схемы данных. Ниже — типовые варианты развёртывания, с которыми мы стыкуем модули, и ограничения, которые честнее увидеть до старта, чем на этапе выката.
Отдельно проверяем существующий стек: СУБД и её мажорную ветку, способ аутентификации (внешний провайдер, LDAP, SSO), хранилище файлов (локальное, S3-совместимое), обратный прокси и политику резервного копирования. Модуль, который пишет в базу напрямую в обход слоя доступа, ломает права и аудит — поэтому все операции идут через штатные интерфейсы платформы.
Directus остаётся ядром, а модуль — расширением: обновление платформы не превращается в переписывание логики. Опишите ваш вариант развёртывания и текущий стек — вернёмся с оценкой совместимости и планом работ.
