Битрикс24 и БУС
Локальный модуль Битрикс24: границы, обновления и сопровождение
Как определить ответственность локального модуля, отделить бизнес-логику от интерфейса и подготовить изменение к сопровождению.
Локальный модуль помогает собрать связанную прикладную логику в одном месте. Но путь /local/modules/ сам по себе не делает решение независимым от версии платформы. Важно определить ответственность модуля, его зависимости и сценарии, которые нужно проверять после обновления.
Материал посвящён устройству решения. Он не является готовым установщиком и не обещает совместимость со всеми редакциями БУС и Битрикс24.
Когда модуль оправдан
Модуль полезен, если у функции есть собственные настройки, данные, права, интеграционные операции или несколько точек входа. Например, одна и та же проверка может понадобиться в интерфейсе, агенте и административной операции.
Если задача решается небольшой настройкой стандартного инструмента, дополнительный модуль может оказаться лишним. Решение стоит выбирать по жизненному циклу функции, а не по размеру первого фрагмента кода.
Одна операция — одна прикладная ответственность
Предположим, нужно принять заявку и передать её во внешнюю систему. Удобно различать три части:
| Часть | Ответственность |
|---|---|
| Точка входа | Получить запрос, проверить сессию и право на действие, подготовить ответ |
| Прикладная операция | Проверить правила заявки и согласованно изменить её состояние |
| Адаптер внешней системы | Сформировать внешний запрос, разобрать результат и классифицировать ошибку |
Такой разбор не требует трёх больших фреймворков или сложной иерархии. Он нужен, чтобы изменение интерфейса не заставляло переписывать обмен, а ошибка обмена не терялась внутри HTML-ответа.
Проверку прав важно выполнять на стороне сервера. Скрытая кнопка не мешает отправить запрос напрямую. Контекст фоновой операции тоже должен быть явным: кто её инициировал и от чьего имени она может менять данные.
Использовать точки расширения осознанно
События платформы позволяют подключать собственную логику к определённому моменту операции. Перед регистрацией обработчика нужно проверить сигнатуру события, его условия и последствия ошибки именно в нужной версии модуля.
Долгую сетевую операцию стоит оценить отдельно: если она выполняется внутри пользовательского запроса, недоступность внешней системы может задерживать весь сценарий. В зависимости от задачи может понадобиться постановка работы в очередь.
Документация D7 и EventManager помогают найти доступные механизмы. При использовании внутренних недокументированных методов ответственность за проверку изменений выше: наличие метода в одной версии не является обещанием стабильного контракта.
Данные и установка
Установка, обновление и удаление — разные операции. Обновление не должно требовать удаления модуля с потерей накопленных данных. Решение о сохранении данных при удалении должно быть понятным администратору.
Изменения структуры данных полезно оформлять воспроизводимыми шагами. Нужно проверить запуск на новой установке и обновление с предыдущей поддерживаемой версии. Состав этой проверки определяется тем, что реально менялось.
При работе через ORM следует отдельно проверить бизнес-правила конкретной сущности. Универсальная операция сохранения записи не всегда равнозначна штатной операции продукта со всеми событиями, правами и побочными действиями.
Что передать сопровождающему разработчику
- Назначение модуля и границы его ответственности.
- Поддерживаемое окружение и существенные зависимости.
- Точки входа, события, фоновые задания и настройки.
- Порядок установки, обновления и возврата к предыдущему состоянию.
- Примеры вызова публичных методов и ожидаемые ошибки.
- Короткие сценарии проверки после изменения или обновления платформы.
Особенно полезен пример неуспешной операции: как обнаружить проблему, где искать диагностическую запись и при каких условиях можно повторить действие. Такое описание снижает зависимость проекта от памяти автора.
Как проверить готовность
Попросите другого разработчика выполнить один основной сценарий по документации и объяснить, что произойдёт при ошибке. Если для этого приходится искать автора и расспрашивать о неявных настройках, передача решения ещё не завершена.