Разработка headless-архитектуры на 1С-Битрикс

Разработка headless-архитектуры на 1С-Битрикс

Монолитная архитектура 1С-Битрикс с шаблонами и компонентами прекрасно работала, когда сайт был единственной точкой контакта с клиентом. Сегодня тот же каталог должен отдаваться в мобильное приложение, в PWA, в голосовые ассистенты, во внешние сервисы агрегаторов. Компонентный подход Битрикса для этого не подходит — он генерирует HTML, а не JSON.

Headless-архитектура разделяет Битрикс на бэкенд (бизнес-логика, данные, API) и независимый фронтенд. Битрикс становится headless CMS — управляет контентом и данными, не генерируя HTML.

Архитектурная схема

[1С-Битрикс Backend]
  ├── Инфоблоки (каталог, контент)
  ├── Торговый каталог (цены, остатки)
  ├── CRM / Заказы
  └── REST API Layer
         |
    [API Gateway / nginx]
         |
    ┌────┴─────────────┐
[React SPA]    [Mobile App]    [Внешние сервисы]

Битрикс сохраняет всю бизнес-логику: обработка заказов, сеансы, корзина, авторизация, интеграция с 1С. Фронтенд — независимо разрабатываемое и деплоимое React/Next.js приложение.

REST API в 1С-Битрикс

Битрикс не имеет встроенного REST API уровня Next.js или Laravel. API строится двумя способами:

1. Контроллеры через addAjaxAction (старый, но рабочий способ):

// /local/ajax/catalog.php
define('STOP_STATISTICS', true);
define('NO_KEEP_STATISTIC', 'Y');
define('BX_SECURITY_SHOW_MESSAGE', true);

require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

header('Content-Type: application/json; charset=UTF-8');
header('Access-Control-Allow-Origin: https://your-frontend.com');

CModule::IncludeModule('iblock');

$action = $_GET['action'] ?? '';

if ($action === 'catalog') {
    $items = getCatalogItems($_GET);
    echo json_encode(['status' => 'ok', 'data' => $items]);
}

2. Роутер через bitrix/routing (Битрикс 20+, рекомендуемый подход):

// local/routes/api.php
use Bitrix\Main\Routing\RoutingConfigurator;

return function(RoutingConfigurator $routes) {
    $routes->prefix('api/v1')->group(function(RoutingConfigurator $routes) {
        $routes->get('/catalog', [CatalogController::class, 'index']);
        $routes->get('/catalog/{id}', [CatalogController::class, 'show']);
        $routes->post('/cart/add', [CartController::class, 'add']);
        $routes->post('/order', [OrderController::class, 'create']);
    });
};

// local/controllers/CatalogController.php
class CatalogController extends \Bitrix\Main\Engine\Controller {
    public function indexAction(int $page = 1, int $limit = 20): array {
        $items = \Bitrix\Iblock\Elements\ElementCatalogTable::getList([
            'filter' => ['ACTIVE' => 'Y', 'IBLOCK_ID' => CATALOG_IBLOCK_ID],
            'limit'  => $limit,
            'offset' => ($page - 1) * $limit,
        ]);

        return ['items' => $items->fetchAll(), 'page' => $page];
    }
}

Аутентификация и сессии

Headless-архитектура разрушает стандартную сессионную авторизацию Битрикса. Два подхода:

JWT-токены. Пользователь авторизуется через API, получает JWT, прикладывает к каждому запросу. Битрикс валидирует токен и определяет пользователя:

// Middleware для валидации JWT
function validateJwtToken(string $token): ?int {
    $payload = JWT::decode($token, new Key(JWT_SECRET, 'HS256'));
    return $payload->userId ?? null;
}

Cookie + CORS. Сохраняете стандартную сессию Битрикса, но настраиваете CORS для фронтенд-домена. Проще в реализации, сложнее в безопасности (CSRF-защита обязательна).

Кэширование API-ответов

Без кэширования headless-Битрикс медленный — каждый запрос к каталогу полностью строит выборку из БД. Многоуровневое кэширование:

// CDN-кэш для статичных данных каталога (Redis + nginx)
public function indexAction(): array {
    $cacheKey = 'catalog_page_' . $this->getCurrentPage();
    $cache = Cache::createInstance();

    if ($cache->initCache(3600, $cacheKey, '/catalog/')) {
        return $cache->getVars()['data'];
    }

    $data = $this->buildCatalogData();

    $cache->startDataCache();
    $cache->endDataCache(['data' => $data]);

    return $data;
}

Кэш инвалидируется при изменении данных инфоблока через BXClearCache(true, '/catalog/') в обработчике событий OnAfterIBlockElementUpdate.

Деплой и CORS

Headless требует правильного разделения доменов: api.yoursite.ru (Битрикс) и yoursite.ru (фронтенд Next.js на Vercel/Nginx). Настройка CORS в nginx для API-сервера:

location /api/ {
    add_header 'Access-Control-Allow-Origin' 'https://yoursite.ru';
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
    add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type';
    add_header 'Access-Control-Allow-Credentials' 'true';

    if ($request_method = 'OPTIONS') {
        return 204;
    }

    fastcgi_pass php-fpm;
}

Headless на Битриксе — это архитектурное решение с ощутимыми преимуществами (независимый фронтенд, скорость, мультиканальность) и реальными затратами (разработка API, кэширование, CORS, инфраструктура). Принимайте это решение осознанно, когда монолит действительно стал ограничением, а не из моды на headless.