Bitrix API и версия: имя метода не обещает одинаковый контракт

Проблема версионной совместимости выглядит как простой поиск: в документации найден метод, значит его можно вызвать. В Bitrix такой вывод часто слишком сильный. Один и тот же смысл может жить в legacy-классе и в D7, а конкретная установка может не содержать нужный модуль или иметь изменённое поле. Цена ошибки — адаптер, который компилируется и падает только на редкой форме или после обновления.

Надёжная граница строится из трёх фактов: модуль подключён, поверхность методов действительно доступна, а вход и выход совпадают с нужным проекту контрактом. Версия помогает сузить поиск, но не заменяет проверку. Даже правило Semantic Versioning применимо только там, где поставщик соблюдает его для данного API; имя Update само по себе не обещает семантическую совместимость.

Подключение модуля — часть контракта

Документация Bitrix для CModule::IncludeModule прямо описывает проверку установки и подключения модуля. Это не декоративная строка перед вызовом. Если модуль не подключён, сообщение об ошибке может появиться далеко от места, где принято решение использовать API. В адаптере проверка должна быть близко к границе и возвращать понятный результат, который можно показать в диагностике.

Для D7 аналогично нужен конкретный namespace и набор методов. Нельзя заменить CUser на Bitrix\Main\UserTable, не проверив mapping полей, типы значений и обработку исключений. Хорошее сравнение описывает не названия классов, а операции: создать, обновить, найти, получить ID, обработать ошибку. Именно операции должны попасть в тестовую матрицу.

Локальный инспектор поверхности

Чтобы сделать проверку повторяемой, можно сначала работать с маленьким manifest, полученным из конкретного окружения: версия, признак подключения и список доступных операций. Ниже функция принимает такой manifest и выбирает следующий технический шаг. Она не делает вид, что знает реальный сервер: данные нужно собрать командой проверки в самой среде, а функция только не даёт перепутать отсутствие модуля с отсутствием метода.

import { inspectBitrixSurface } from './upgrade-2027-02.mjs';

const surfaces = [
  { version: '20.0', moduleLoaded: false, methods: [] },
  { version: '20.0', moduleLoaded: true, methods: ['CUser::GetByID', 'CUser::Update'] },
  { version: '23.0', moduleLoaded: true, methods: ['Bitrix\Main\UserTable'] },
];

for (const surface of surfaces) console.log(inspectBitrixSurface(surface));
// module-not-loaded
// legacy-surface-present
// d7-surface-present

Здесь важен порядок. Первый manifest не доходит до анализа методов: отсутствует базовое условие. Второй разрешает говорить только о наличии legacy-поверхности и требует явного адаптера. Третий показывает D7-поверхность, но не объявляет mapping полей готовым. Такой результат проще проверять в CI или в диагностической команде, чем свободный текст в issue.

Поле важнее красивого имени

Самая тихая ошибка миграции — значение сохранилось, но стало другим. Телефон мог быть строкой с пробелами и плюсами, email — сохранён с исходным регистром, пустое поле — означать «очистить», а отсутствие поля — «не менять». Если новый API получает обычный объект без различия этих состояний, wrapper стирает смысл запроса. Поэтому contract table должна перечислять хотя бы value, empty и missing.

Version boundary нужно держать рядом с этой таблицей. Если в старой версии поле принимает строку, а новая модель отдаёт массив значений, название свойства не спасёт. Правильная проверка — пройти create/read/update на фиксированных данных и сравнить смысловой результат. Одинаковый ID после update ещё не доказывает, что события и индексы получили тот же input.

Действия по порядку

1. Зафиксировать версию ядра, подключаемый модуль и источник документации, на который опирается вызов.
2. Собрать manifest доступных методов или таблиц из той среды, где будет выполняться изменение.
3. Разложить операцию на поля, пустое значение, отсутствие поля, ошибку и побочный event.
4. Проверить legacy и D7 на одном наборе входов, не сравнивая только имена классов или финальный ID.
5. Оставить adapter boundary до тех пор, пока regression не подтвердит одинаковый смысл результата.

Ограничения и следующий шаг

Инспектор не заменяет запуск в Bitrix: он не видит автозагрузку, права, события, local overrides и SQL-ограничения. Номер версии может быть установлен, но отдельный модуль — отсутствовать. Semantic Versioning тоже не заставляет внутренний API платформы соблюдать обещания внешнего пакета. Любое утверждение о совместимости должно опираться на конкретный набор окружений и операций.

Следующий шаг — добавить в проект диагностическую команду, которая печатает только безопасный manifest: версия, подключённый модуль и названия операций без данных пользователей. Затем используйте его перед миграцией одного метода. Если surface различается, адаптер должен остановить изменение с понятной причиной, а не подобрать метод по совпадению имени.

Проверяемые источники

• CModule::IncludeModule — документация 1С-Битрикс — версия и дата: документация API, проверена 31 July 2026; CModule с версии 3.0.1. Применение: Официальная проверка подключения модуля используется как первый слой version boundary. Граница: Документация не сообщает состояние конкретной установки и не описывает mapping полей.
• Главный модуль: CUser — документация 1С-Битрикс — версия и дата: документация API, проверена 31 July 2026; класс доступен с версии 3.0.6. Применение: CUser и его D7-аналог используются для различения поверхности API и операций пользователя. Граница: Страница не обещает, что два класса равны по событиям, типам и ошибкам.
• Semantic Versioning 2.0.0 — версия и дата: Version 2.0.0, 2013. Применение: Правило совместимости версий используется как оговорка о границах обещаний поставщика. Граница: Спецификация не делает Bitrix API Semantic Versioning-совместимым автоматически.