Проектный модуль в Битриксе: не продукт, а инфраструктура

Откуда берется миф «модуль = переносимость»

Если вы росли на БУС эпохи init.php, обработчиков событий и копипасты компонентов, то модуль обычно воспринимался как:

• «что-то большое и страшное»;
• «то, что пишут только под Маркетплейс»;
• «источник обновлений, которые иногда ломают проект».

В такой картине мира логично думать: если задача проектная и уникальная — значит, это не модуль.

Но эта логика относится к старой реальности, где модуль — это в основном механизм поставки функционала в экосистеме БУС.

Сейчас в Bitrix Framework модуль — это прежде всего способ договориться с системой: где живет ваш код, как он загружается, как он регистрирует сервисы, маршруты, консольные команды и остальную инфраструктуру.

Что на самом деле дает модуль в 2026

Если говорить по-честному, «проектный модуль» нужен не затем, чтобы его переносить. Он нужен затем, чтобы:

1. Собрать код в одном месте, которое система понимает.
2. Включить инфраструктуру Framework-уровня без костылей.
3. Сделать границы предметной области явными.

Это не про «универсальность». Это про «управляемость».

В реальном проекте модуль чаще всего выполняет роль того, что в других фреймворках называется «application package»: контейнер для вашей доменной логики, которую вы хотите развивать годами.

Модуль как карта проекта: бизнес-логика должна иметь адрес

Есть еще одна причина, о которой редко говорят вслух, но именно она делает модуль по-настоящему полезным в командной разработке: модуль задает нормальный «адрес» бизнес-логике.

Если команда придерживается простой договоренности «каждая подсистема живет в своем проектном модуле», вы получаете эффект, который невозможно купить никакими «код-стайлами»:

• новый разработчик приходит на проект и не ищет логику по всему local/;
• он открывает /local/modules/ и видит список доменов: project.catalog, project.blog, project.cabinet, project.news;
• дальше все просто: нужно поменять правила личного кабинета — значит, вы почти наверняка идете в project.cabinet.

Это звучит банально, но это прямой удар по привычке «складывать всё куда-то в /local/php_interface/», когда логика размазана между init.php, обработчиками и случайными include’ами. В такой модели проект превращается в набор сюрпризов: вы не знаете, где искать код, пока не потратите полдня на раскопки.

Проектный модуль делает обратное: превращает архитектуру в навигацию. И да, это тоже часть инфраструктуры.

Почему Service Locator почти неизбежно ведет к модулю

Service Locator — это удобный мост между «старыми» и «новыми» частями Битрикса. И он особенно полезен там, где вы не можете нормально внедрять зависимости через конструктор: компоненты, обработчики событий, легаси-слой.

Но вот что важно: когда вы переходите от «одного класса» к «набору сервисов», у вас появляется вопрос: где они живут и как регистрируются?

Ответ «просто подключим файл» работает ровно до первого серьезного проекта. Дальше начинается классическая история, описанная в статье «Проблема двух ядер: Как не сойти с ума при поддержке Битрикс-проектов в 2026 году»:

• в одном месте у вас аккуратные сервисы и DTO,
• в другом — процедурная магия,
• между ними — не договор, а случайность.

Модуль — это способ сделать эту границу формальной. Не на словах, а в структуре проекта.

«Но мой код уникален, его нельзя переносить»

Да. И это нормально.

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

Проектный модуль дает вам:

• предсказуемую структуру (где DTO, где сервисы, где репозитории);
• единую точку регистрации (DI, роуты, события);
• понятные зависимости (какие модули нужны, какие сервисы публичные);
• возможность строить «новый мир» внутри старого, не размазывая код по всему local/.

И это ключевой тезис: модуль — это не «упаковка для переезда». Это «фундамент, чтобы не развалилось».

Когда модуль действительно избыточен

Есть честные случаи, когда модуль не нужен:

• разовая правка шаблона или мелкий хук, который не станет системой;
• короткий проект «на сезон», который точно не будет жить долго;
• простой сайт без интеграций и без доменной сложности.

Но как только вы говорите словами «предметная область», «сервисы», «контракты», «API», «валидация», «DTO» — вы уже играете в другую игру. И в этой игре модуль становится не роскошью, а самым дешевым способом не платить за хаос позже.

Кстати, это же объясняет, почему официальная документация чаще описывает «что есть» и «как включить», а не «как проектировать»: «как проектировать» — это про ваш проект и ваш масштаб. Эту мысль я формулировал в посте по новой документации Bitrix Framework.

Что лучше: «решение» (просто классы) или модуль

Правильная формулировка выбора такая:

• либо вы строите систему так, чтобы она жила по законам Bitrix Framework;
• либо вы строите систему так, чтобы она держалась на дисциплине разработчиков и договоренностях в голове.

Можно жить и так, и так. Но когда команда меняется, сроки сжимаются, появляются интеграции и легаси, второй вариант быстро превращается в «археологию».

Ошибка, которая убивает идею модулей

Самая частая причина, почему модуль «не заходит» — попытка сделать его сразу «идеальным» и «универсальным».

Проектный модуль должен быть простым:

• один домен или одна большая подсистема;
• понятные публичные сервисы;
• минимум магии;
• структура, которую можно объяснить новичку за 10 минут.

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