steelmorgan/api-design

API Design — проектирование и ревью интерфейсов подсистем 1С

Основано на статье Infostart «База по API»: https://infostart.ru/1c/articles/2683808/.

Назначение

1С в корпоративных решениях — это модульный монолит: библиотеки состоят из функциональных подсистем, а подсистемы общаются через задекларированные интерфейсы. Произвольный вызов через границы подсистем — это архитектурный дефект, а не удобный приём. Навык учит агента правильно классифицировать экспортные методы, определять допустимость изменений и проектировать API с учётом совместимости.

---

Когда применять

| Триггер | Действие | |---------|----------| | Проектирование нового общего модуля или экспортного метода | Применить классификацию интерфейса (5 категорий), задокументировать контракт | | Изменение сигнатуры существующего экспортного метода | Проверить обратную совместимость по таблице ниже | | Добавление параметра в экспортный метод | Определить — обязательный или нет; оценить impact на версию | | Удаление или переименование экспортного метода | Создать deprecated-обёртку в УстаревшиеПроцедурыИФункции | | Ревью кода: вызов метода из чужой подсистемы | Проверить категорию вызываемого метода (разрешён ли вызов?) | | Ревью кода: изменение поведения без смены сигнатуры | Проверить, не нарушает ли это контракт (Программный интерфейс) | | Вопрос о bump версии при выпуске изменений | Применить правила версионирования (секция «Версионирование») |

---

Классификация экспортных методов (5 категорий БСП)

Каждый экспортный метод обязан принадлежать ровно одной из 5 категорий. Для категорий 1, 2, 4, 5 категория определяется #Областью модуля, в которой находится метод. Исключение — категория 3: она определяется тем, что метод лежит в переопределяемом модуле (*Переопределяемый), а не отдельным регионом — внутри такого модуля методы находятся в обычной #Область ПрограммныйИнтерфейс.

1. #Область ПрограммныйИнтерфейс

Публичный контракт для внешних потребителей — других библиотек, прикладных решений, интеграций.

• Обратная совместимость обязательна.
• Любое изменение, которое ломает существующих потребителей, требует deprecated-обёртки.
• Добавление необязательного параметра — допустимо, но требует bump версии.

#Область ПрограммныйИнтерфейс

// Возвращает курс валюты на указанную дату.
//
// Параметры:
//  Валюта    - СправочникСсылка.Валюты - валюта, курс которой нужно получить.
//  ДатаКурса - Дата - дата, на которую нужен курс.
//              Если не указана, используется текущая дата сеанса.
//
// Возвращаемое значение:
//  Число - курс валюты. 0 если курс не найден.
//
Функция КурсВалюты(Валюта, ДатаКурса = Неопределено) Экспорт
    Возврат РаботаСВалютами.КурсВалюты(Валюта, ДатаКурса);
КонецФункции

#КонецОбласти

2. #Область СлужебныйПрограммныйИнтерфейс

Контракт для вызова из других модулей внутри одной библиотеки (не для внешних потребителей).

• Прямая обратная совместимость не гарантируется, но изменения документируются.
• Вызов из другой библиотеки — дефект, если нет явного соглашения.

#Область СлужебныйПрограммныйИнтерфейс

// Обновляет кэш курсов валют при изменении данных.
// Вызывается только из подписки на событие РаботаСВалютамиОбновлениеКурсов.
//
Процедура ОбновитьКэшКурсовВалют() Экспорт
    // ...
КонецПроцедуры

#КонецОбласти

3. Переопределяемые модули (*Переопределяемый)

Точка расширения: библиотека вызывает метод потребителя через модуль с суффиксом Переопределяемый (например, РаботаСФайламиПереопределяемый). Региона «ПереопределяемыйИнтерфейс» не существует — «переопределяемость» это свойство самого модуля (его назначение в архитектуре БСП), а не региона внутри него; методы таких модулей находятся в обычной #Область ПрограммныйИнтерфейс.

• Нельзя добавлять новые обязательные параметры в существующие процедуры.
• Нельзя менять типы параметров.
• Нельзя удалять параметры, которые существующие реализации могут получать.
• Новые процедуры и необязательные параметры допустимы, если старые реализации продолжают работать (пустая реализация новой точки расширения сохраняет прежнее поведение).

// Модуль: РаботаСФайламиПереопределяемый
#Область ПрограммныйИнтерфейс

// Определяет настройки хранения присоединённых файлов.
//
// Параметры:
//  НастройкиХранения - Структура - настройки, которые нужно заполнить.
//
Процедура ОпределитьНастройкиХраненияФайлов(НастройкиХранения) Экспорт

    // Обязательно вызовите Базовую реализацию или заполните структуру самостоятельно.

КонецПроцедуры

#КонецОбласти

4. #Область ДляВызоваИзДругихПодсистем

Стабильная зона интеграции между подсистемами одного решения.

• Методы стабильны, но не являются публичным API библиотеки.
• Вызов из другой библиотеки без явного контракта — дефект.
• Изменения согласовываются с командами-потребителями.

5. #Область СлужебныеПроцедурыИФункции

Внутренняя реализация одной функциональной подсистемы. Не экспортируются.

• Вызов из другой подсистемы — дефект (кроме случаев, явно задокументированных в проекте).
• Если метод экспортный и находится в этой области — либо снять Экспорт, либо переместить в нужную категорию.

---

Правила обратной совместимости

Что не ломает (можно в build-bump)

| Изменение | Условие | |-----------|---------| | Добавление необязательного параметра | Старые вызовы работают без него | | Добавление нового метода в ПрограммныйИнтерфейс | Не конфликтует с именами потребителей | | Изменение реализации без изменения поведения | Контракт не нарушается | | Исправление ошибки в реализации | Документируется в changelog |

Что ломает совместимость (требует version-bump или deprecated-обёртки)

| Изменение | Требование | |-----------|------------| | Добавление обязательного параметра | Сохранить старую сигнатуру как deprecated, новый метод — новое имя или overload | | Удаление метода из ПрограммныйИнтерфейс | Deprecated-обёртка в УстаревшиеПроцедурыИФункции + migration path | | Переименование метода | Deprecated-обёртка со старым именем | | Изменение типа параметра (несовместимое) | Deprecated-обёртка, новый параметр — через опциональный или перегрузку | | Изменение смысла параметра (behavior break) | Новое имя параметра или документирование breaking change | | Прямой доступ к данным другой подсистемы | Запрещён без явного API |

Приоритет совместимости над стилем

Требования обратной совместимости перекрывают косметические стандарты. Нельзя переименовать публичный метод «для правильного стиля» без deprecated-обёртки.

---

Deprecated-области и миграция

При устаревании метода:

1. Переместить метод в #Область УстаревшиеПроцедурыИФункции.
2. Добавить в заголовок метода: // Устарела. Используйте <НовыйМетод>().
3. Внутри вызвать новый метод (adapter pattern).
4. Указать версию удаления или условие удаления.

#Область УстаревшиеПроцедурыИФункции

// Устарела. Используйте КурсВалютыНаДату().
// Будет удалена в версии 4.0.
//
// Параметры:
//  Валюта    - СправочникСсылка.Валюты
//  ДатаКурса - Дата
//
// Возвращаемое значение:
//  Число
//
Функция ПолучитьКурсВалюты(Валюта, ДатаКурса) Экспорт
    Возврат КурсВалютыНаДату(Валюта, ДатаКурса);
КонецФункции

#КонецОбласти

---

Версионирование интерфейса

| Тип изменения | Bump | |---------------|------| | Исправление ошибки без изменения поведения API | build (x.x.x.N) | | Новый необязательный параметр, новый метод в ПИ | minor (x.N.0.0) | | Breaking change с deprecated-обёрткой | minor + документирование | | Удаление deprecated-метода, несовместимый тип | major (N.0.0.0) |

Запрещено: вносить расширение публичного API (новые методы, новые параметры) в релиз с bump только по build. Build — только для bug fix.

---

Workflow ревью API

Шаг 1. Разведка

Используй code-navigation (grep по исходникам) для поиска:

• Метода по имени — найти его объявление и определить #Область.
• Всех мест вызова метода — оценить круг потребителей.
• Секций #Область УстаревшиеПроцедурыИФункции — проверить наличие deprecated-обёрток.

// Поиск объявления метода
// grep: "Функция КурсВалюты" или "Процедура КурсВалюты"

// Поиск вызовов
// grep: "РаботаСВалютами.КурсВалюты"

// Поиск deprecated-области
// grep: "Устаревшие процедуры и функции"

Шаг 2. Классификация изменения

Определить, к какой категории относится метод, и выбрать из таблицы ниже:

| Тип изменения | Категория метода | Требование | |---------------|-----------------|------------| | Новый метод | Любая | Разместить в правильной #Области | | Новый необязательный параметр | ПрограммныйИнтерфейс | Допустимо, version bump | | Новый обязательный параметр | ПрограммныйИнтерфейс | Deprecated-обёртка обязательна | | Удаление метода | ПрограммныйИнтерфейс | Deprecated-обёртка обязательна | | Изменение поведения | ПрограммныйИнтерфейс | Считается breaking change | | Любое изменение | СлужебныеПроцедурыИФункции | Свободно (внутри подсистемы) | | Новый обязательный параметр | Переопределяемые модули (*Переопределяемый) | Запрещено |

Шаг 3. Проверка через syntax-checking

После изменения сигнатуры:

• Запустить статический анализ на вызывающие модули.
• Убедиться, что нет BSL LS предупреждений типа «метод не найден», «неверное количество параметров».
• Если предупреждения подавлены без документирования причины — это красный флаг.

Шаг 4. Документирование контракта

Каждый метод из #Область ПрограммныйИнтерфейс — в том числе методы переопределяемых модулей (*Переопределяемый) — должен иметь:

• Описание назначения.
• Параметры с типами и описанием (включая необязательные и значения по умолчанию).
• Возвращаемое значение (для функций).
• Примечания о поведении (исключения, граничные случаи).

---

Сценарии использования

Сценарий 1: Добавление нового метода в общий модуль

Контекст: developer просит добавить функцию ПолучитьОстатокТоваров() в общий модуль УправлениеЗапасами.

Шаги:

1. Определить, для кого метод — внешние потребители или только эта подсистема.
2. Если для внешних — разместить в #Область ПрограммныйИнтерфейс.
3. Написать полный comment-header с типами параметров.
4. Убедиться, что не экспортируется лишнего (реализация — в СлужебныеПроцедурыИФункции).
5. Отметить в changelog: новый метод ПИ → minor version bump.

Сценарий 2: Ревью изменения сигнатуры

Контекст: reviewer получает PR, где у метода РаботаСВалютами.КурсВалюты() добавлен новый обязательный параметр ИсточникКурса.

Шаги:

1. code-navigation: найти все вызовы РаботаСВалютами.КурсВалюты( — оценить количество потребителей.
2. Проверить #Область метода — если ПрограммныйИнтерфейс, то breaking change.
3. Потребовать: старую сигнатуру перенести в УстаревшиеПроцедурыИФункции с вызовом нового метода.
4. Новый метод с обязательным параметром — новое имя (КурсВалютыИзИсточника) или сделать параметр необязательным.

Сценарий 3: Проектирование переопределяемого модуля

Контекст: architect проектирует новую точку расширения для механизма уведомлений.

Шаги:

1. Определить процедуры, которые будут вызываться библиотекой.
2. Все параметры сделать либо структурами (легко расширяются), либо строго задокументировать типы.
3. НЕ добавлять обязательные параметры в процедуры точки расширения после релиза — только необязательные.
4. Задокументировать контракт: что библиотека передаёт, что ожидает на выходе.
5. Разместить в отдельном переопределяемом модуле (ИмяПодсистемыПереопределяемый), в его обычной #Область ПрограммныйИнтерфейс — не в специальном регионе.

Сценарий 4: Обнаружение нарушения при ревью

Контекст: reviewer замечает вызов ЧастнаяПодсистема.ВнутреннийМетод() из чужого модуля.

Шаги:

1. Найти #Область вызываемого метода.
2. Если СлужебныеПроцедурыИФункции — это дефект, зафиксировать в замечании.
3. Предложить альтернативу: создать метод в ДляВызоваИзДругихПодсистем или ПрограммныйИнтерфейс.
4. Если метод СлужебныйПрограммныйИнтерфейс и вызов из другой библиотеки — запросить явное соглашение или рефакторинг.

---

Типичные ошибки

| Ошибка | Последствие | Как избежать | |--------|-------------|--------------| | Вызов СлужебныеПроцедурыИФункции из другой подсистемы | Хрупкая интеграция, break при рефакторинге | Проверять #Область перед вызовом | | Добавление обязательного параметра без deprecated-обёртки | Break всех вызовов в CI | Всегда создавать adapter в УстаревшиеПроцедурыИФункции | | API-расширение в build-only релизе | Нарушение версионирования, путаница у потребителей | Build — только для bug fix | | Метод переопределяемого модуля (*Переопределяемый) с новым обязательным параметром | Ошибки у всех существующих реализаций | Только необязательные параметры в переопределяемых | | Изменение смысла параметра без документирования | Молчаливый behavioral break | Документировать в changelog, consider version bump | | Подавление предупреждений BSL LS без причины | Скрытые breaking changes | Всегда документировать причину подавления | | Прямой доступ к таблицам данных другой подсистемы | Жёсткая связанность, архитектурный долг | Использовать только задокументированный API |

---

Чеклист API-first проектирования

Перед реализацией нового API:

• [ ] API действительно нужен (нет более простого способа)
• [ ] Определены use-cases и потребители
• [ ] Выбрана категория (#Область) для каждого метода
• [ ] Описан контракт: параметры, типы, исключения, idempotency
• [ ] Определена стратегия версионирования
• [ ] Написаны тесты, моделирующие вызовы потребителей
• [ ] Changelog и уведомление потребителей запланированы

---

Связанные ресурсы

• coding-standards — структура модуля (#Область), правила комментирования экспортных методов
• test-writing — написание тестов, моделирующих вызовы API
• ssl-patterns — паттерны работы с БСП (подсистемы, вызовы через интерфейс)
• Статья «База по API»: https://infostart.ru/1c/articles/2683808/

---

depends_on:

• bsl-practices/coding-standards
• bsl-practices/test-writing

---