Версии · 8 мин
Контракты, версии и границы применимости
Как не превратить верный пример из другой версии в ошибочную рекомендацию.
Похожий фрагмент кода может быть безупречным — и всё равно не подходить вашему проекту. Разница часто скрыта не в синтаксисе, а в версии платформы, библиотеки, формата обмена или способа вызова.
Пример без координаты версии — только кандидат. Доказанный ответ всегда называет область применимости и действие на случай несовместимости.
Контракт — это проверяемое обещание системы
В прикладной разработке 1С контрактом удобно называть утверждённый формат данных и правила вызова. Для экспортной функции общего модуля это имя, параметры, тип результата, доступность на клиенте или сервере и ожидаемые ошибки. Для обмена — обязательные поля, допустимые значения и порядок обработки ответа.
Контракт полезен агенту потому, что превращает расплывчатое «сделай как принято» в набор проверяемых условий. Если источник не сообщает контекст выполнения или версию, эти сведения нельзя восстановить одной уверенностью модели.
Параметры, типы, обязательные значения и предусловия.
Результат, ошибки и признаки успешного выполнения.
Клиент, сервер, транзакция, права и допустимая точка вызова.
Диапазон поддержки, статус и безопасная замена.
Целевая версия — часть вопроса, а не уточнение после ответа
В библиотечном корпусе знание хранится вместе с координатой: какая версия платформы, прикладной библиотеки 1С или внешнего формата описана. Эта координата не доказывает, что именно такая версия используется в проекте. Значение настройки, зависимость или режим совместимости нужно отдельно найти в проектном контексте.
Если целевая версия неизвестна, безопасный ответ не выбирает самую новую. Он перечисляет найденные варианты, показывает различия и просит подтвердить координату до изменения кода.
- не смешивать документацию разных выпусков в одну рекомендацию;
- отличать поддерживаемый способ от переходного и устаревшего;
- связывать каждую ячейку матрицы совместимости с источником и проверкой;
- останавливаться, если сочетание версий не подтверждено.
Совместимость — это не один флажок
В синтетическом корпусе доставки матрица route-delivery-compatibility / 2.1.0 / custom различает рекомендуемую связку API 2.1.0, JSON Schema 1.4.2 и BSL SDK 1.2.0 с платформой 8.3.20+ и базовую связку API 1.4.0, схем 1.1.6 и SDK 0.8.4 с платформой 8.3.18+. Базовая поддержка не становится рекомендуемой автоматически.
Отдельно фиксируются известные ошибки. Запись об ошибке должна содержать идентификатор, симптом, условия воспроизведения, затронутую версию и безопасное действие. Если запись не найдена, это означает только отсутствие подтверждения в доступном корпусе, а не отсутствие дефекта.
Рекомендуемая связка для платформы 8.3.20 и новее.
Базовая поддержка для платформы 8.3.18 и новее.
Остановиться: автоматическая совместимость не доказана.
Пять проверок перед рекомендацией
Сначала зафиксируйте требуемое поведение, затем найдите контракт нужной версии. После этого подтвердите реальную версию проекта, проверьте известные ограничения и только затем выбирайте способ вызова. Последний шаг — тест или контролируемый запуск, который проверяет не текст рекомендации, а наблюдаемое поведение.
Что должно происходить и в каком контексте.
Какой формат или вызов разрешён.
Какая версия фактически используется.
Как подтвердить результат выполнением.
Несовместимое сочетание нельзя «починить» догадкой
Вымышленный проект работает на платформе 8.3.19, а найденная связка API 2.1.0 и BSL SDK 1.2.0 требует платформу 8.3.20 и новее по матрице совместимости. Код выглядит знакомо, но область применимости не совпадает.
- Зафиксировать найденную версию платформы как факт проекта.
- Открыть матрицу корпуса и увидеть неподтверждённое сочетание.
- Предложить обновление платформы либо подтверждённый переходный комплект.
- Не отправлять запрос и не менять код до выбора допустимой координаты.
Версии, названия библиотек и предметная область вымышлены и существуют только в синтетическом корпусе Route Delivery.
Что уже можно утверждать, а что нужно проверить
- route-delivery-compatibility / 2.1.0 / custom содержит зафиксированную матрицу совместимости и описание миграции.
- Пример без подтверждённой целевой версии не является готовой рекомендацией.
- Фактическую версию платформы, библиотеки и настройки конкретного проекта.
- Результат теста на выбранном сочетании версий.