Публичные SDK¶
Требования применяются к разработке, тестированию и сборке SDK, публикуемого для
независимых потребителей. Уровни обязательности определены в корневом
README.md.
DEV-SDK-001. Объявленная публичная поверхность¶
Уровень: MUST
Применяется к: каждому публикуемому SDK
Публичные модули, типы, функции, ошибки и поддерживаемые runtime должны быть объявлены машинно-проверяемым manifest или генерируемым API-описанием. Внутренний модуль не должен быть доступен через публичную точку входа.
Обоснование¶
Неявный export превращает деталь реализации в поддерживаемый контракт.
Проверка¶
- автоматическое извлечение публичного API;
- проверка exports package;
- compile-тест потребителя только по публичным точкам входа.
Исключения¶
Не допускаются для опубликованного package.
DEV-SDK-002. Совместимость публичного API¶
Уровень: MUST
Применяется к: изменению опубликованного SDK
Удаление, переименование, сужение допустимых входов, изменение результата или ошибки и повышение минимального runtime являются несовместимым изменением. CI должен сравнивать публичный API с предыдущим release и проверять соответствие объявленной версии правилам версионирования проекта.
Обоснование¶
Потребитель обновляет SDK независимо от поставщика.
Проверка¶
- automated API diff;
- compile- и behavior-тест предыдущего потребителя;
- проверка изменения версии package.
Исключения¶
Исправление ещё не опубликованного API не является изменением публичного контракта.
DEV-SDK-003. Соответствие протокольному контракту¶
Уровень: MUST
Применяется к: SDK, инкапсулирующему API или протокол
Сгенерированный и ручной код SDK должен соответствовать зафиксированной версии машинно-проверяемого контракта. Неизвестное значение ответа не должно приводить к успешной интерпретации с другим смыслом. Повторы, timeout, отмена и идемпотентность не должны скрыто изменять контракт вызывающей стороны.
Обоснование¶
Удобная оболочка не должна создавать семантику, отличную от протокола.
Проверка¶
- contract tests по опубликованной схеме;
- тест неизвестных полей и значений;
- тест timeout, отмены и повторного вызова.
Исключения¶
Дополнительная высокоуровневая операция допустима как отдельный явно документированный API SDK.
DEV-SDK-004. Минимальный и воспроизводимый package¶
Уровень: MUST
Применяется к: release package SDK
Package должен собираться из зафиксированного toolchain и содержать только публичный runtime-код, типы, обязательные metadata и лицензионные материалы. Тесты, credentials, внутренние fixtures и build cache не должны публиковаться. Зависимости потребителя и bundled dependencies должны быть разделены согласно семантике package manager.
Обоснование¶
Лишние файлы и неверная классификация зависимостей увеличивают поверхность контракта и риск конфликтов.
Проверка¶
- повторная сборка package;
- проверка списка файлов и dependency metadata;
- установка в чистый минимальный consumer.
Исключения¶
Source maps могут публиковаться, если не содержат закрытого кода или секретов.