Некорректная рекомендация по замене комплексных компонентов на контроллеры в документации #74
Description
Описание проблемы
На странице документации Когда использовать компоненты содержится фраза:
"Если требуется создать полнофункциональный раздел на сайте, например, каталог товаров, то следует использовать контроллер."
При этом слово "контроллер" является ссылкой на раздел Контроллеры (D7), описывающий классы \Bitrix\Main\Engine\Controller.
Почему это архитектурно некорректно
Классы \Bitrix\Main\Engine\Controller предназначены исключительно для:
- Обработки AJAX-запросов
- REST API endpoints
- Возврата JSON/JSONP ответов
Они не предназначены (и не поддерживают технически) для рендеринга полноценных HTML-страниц каталога товаров. Контроллеры D7 работают через JsonResponse или RedirectResponse, но не имеют механизмов для подключения шаблонов компонентов (View) в контексте публичной страницы.
При попытке использовать D7-контроллеры для вывода HTML-разделов возникает архитектурное нарушение (architectural violation): контроллер берет на себя ответственность View-слоя, что противоречит документации ядра D7.
Контекст путаницы
Документация пытается противопоставить "комплексные компоненты" (которые действительно устарели и не рекомендуются) и "контроллеры". Однако:
- Комплексный компонент — это по сути Router + Controller в одном флаконе (парсит URL, выбирает шаблон)
- D7 Controller — это обработчик действий, а не замена механизму маршрутизации для HTML
Правильная альтернатива комплексным компонентам — это:
- Простые компоненты (
catalog.section,catalog.elementи т.п.) - Маршрутизация через urlrewrite.php или D7 Router (для определения URL)
- Разделение физических страниц (section.php, element.php) с явным роутингом
Предлагаемые изменения
Вариант 1: Уточнение терминологии (рекомендуется)
Заменить текущую формулировку на:
"Если требуется создать полнофункциональный раздел на сайте, например, каталог товаров, рекомендуется использовать простые компоненты (
catalog.section,catalog.element) с явной маршрутизацией через urlrewrite.php или D7 Router.Примечание: D7 Controllers (
\Bitrix\Main\Engine\Controller) предназначены для AJAX/API обработки, а не для рендеринга HTML-страниц."
Вариант 2: Исправление ссылки
Если под "контроллером" имелся в виду компонент-роутер (complex router component), ссылка должна вести не на D7 Controllers, а на документацию по архитектуре разделов с использованием простых компонентов и urlrewrite.
Дополнительно
На странице про контроллеры добавить явное предупреждение:
Важно: D7 Controllers не предназначены для генерации HTML-контента публичных страниц. Для рендеринга разделов каталога используйте стандартные компоненты с маршрутизацией.
Почему это важно
Текущая формулировка вводит разработчиков в заблуждение, заставляя их:
- Пытаться рендерить HTML через D7 Controllers (что приводит к костылям)
- Смешивать ответственность слоев MVC
- Игнорировать проверенный подход с urlrewrite.php + простые компоненты
Это особенно критично для новых разработчиков, которые могут воспринять "контроллеры" как замену комплексным компонентам в контексте SEO-ориентированных каталогов.