version: "1.0.1" name: api-design description: "Use for проектирования и ревью публичного API подсистем 1С. Helps классифицировать экспортные методы по 5 категориям, проверить обратную совместимость и спроектировать версионирование с deprecated-обёртками."

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

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

Назначение

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

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

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

Каждый экспортный метод обязан принадлежать ровно одной из 5 категорий. Категория определяется #Областью модуля, в которой находится метод.

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

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

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

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

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

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

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

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

3. #Область ПереопределяемыйИнтерфейс

Точка расширения: библиотека вызывает метод потребителя (через переопределяемые модули).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Workflow ревью API

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

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

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

// Поиск объявления метода
// grep: "Функция КурсВалюты" или "Процедура КурсВалюты"
 
// Поиск вызовов
// grep: "РаботаСВалютами.КурсВалюты"
 
// Поиск deprecated-области
// grep: "Устаревшие процедуры и функции"

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

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

Шаг 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. Если метод СлужебныйПрограммныйИнтерфейс и вызов из другой библиотеки — запросить явное соглашение или рефакторинг.

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

Чеклист 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