Документация библиотеки openfeature

Реализация OpenFeature для OneScript: вендор-независимый API оценки фича-флагов. Приложение настраивает провайдера один раз при старте, а дальше везде работает с клиентом, поэтому систему управления флагами можно сменить, не трогая прикладной код.

1. Разделы документации

Документ	Содержание
Публичный API	Модули и классы: сигнатуры, параметры, примеры
Продуктовое описание	Задача, отличия от альтернатив, спецификация, ограничения
Выпуск релиза	Порядок публикации пакета
examples/	Запускаемые примеры

2. Быстрый старт

#Использовать openfeature

OpenFeature.УстановитьПровайдер(Новый JsonFileProvider("флаги.json"));

Клиент = OpenFeature.ПолучитьКлиента();
Контекст = Новый EvaluationContext("user-42", Новый Структура("plan", "pro"));

Если Клиент.ПолучитьЛогическое("new-checkout", Ложь, Контекст) Тогда
	ПоказатьНовуюКорзину();
КонецЕсли;

3. Как устроена оценка

прикладной код -> FeatureClient -> хуки До -> провайдер -> проверка типа
                                -> хуки После либо ПриОшибке -> хуки Финально

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

Каждая оценка проходит четыре проверки:

Шаг	Что проверяется	Результат при неудаче
Готовность провайдера	Провайдер инициализирован	PROVIDER_NOT_READY
Наличие флага	Флаг известен провайдеру	FLAG_NOT_FOUND
Тип значения	Тип совпадает с запрошенным	TYPE_MISMATCH
Отсутствие сбоя	Провайдер и хуки не выбросили исключение	GENERAL

4. Типы значений

Метод	Тип	Метод с деталями
ПолучитьЛогическое	Булево	ПолучитьЛогическоеСДеталями
ПолучитьСтроку	Строка	ПолучитьСтрокуСДеталями
ПолучитьЧисло	Число	ПолучитьЧислоСДеталями
ПолучитьОбъект	любой	ПолучитьОбъектСДеталями

Сигнатура одинаковая: (Ключ, ЗначениеПоУмолчанию, Контекст = Неопределено, Параметры = Неопределено). Методы без деталей возвращают только значение, методы с деталями - EvaluationDetails.

5. Контексты и их приоритет

Контекст уровня приложения объединяется с контекстом вызова, и контекст вызова важнее: чем ближе контекст к месту решения, тем он значимее. Хук на стадии До может дополнить итоговый контекст, и его атрибуты имеют наивысший приоритет.

OpenFeature.УстановитьГлобальныйКонтекст(Новый EvaluationContext("", Новый Структура("окружение", "prod")));

Клиент.ПолучитьЛогическое("флаг", Ложь, Новый EvaluationContext("user-1"));

6. Свой провайдер

Провайдер - объект со следующими методами:

Функция Метаданные() Экспорт                     // Структура("Имя", "МойПровайдер")
Процедура Инициализировать(Знач Контекст) Экспорт
Процедура Завершить() Экспорт
Функция Состояние() Экспорт                      // NOT_READY, READY, ERROR, STALE, FATAL

Функция ВычислитьЛогическое(Знач Ключ, Знач ЗначениеПоУмолчанию, Знач Контекст) Экспорт
Функция ВычислитьСтроку(Знач Ключ, Знач ЗначениеПоУмолчанию, Знач Контекст) Экспорт
Функция ВычислитьЧисло(Знач Ключ, Знач ЗначениеПоУмолчанию, Знач Контекст) Экспорт
Функция ВычислитьОбъект(Знач Ключ, Знач ЗначениеПоУмолчанию, Знач Контекст) Экспорт

Каждый метод оценки возвращает ResolutionDetails.

7. Хуки

Хук - объект с методами До, После, ПриОшибке, Финально. Любого из них может не быть: отсутствие метода не ошибка.

Стадия	Когда вызывается	Может ли повлиять на результат
До(Данные, Подсказки)	Перед обращением к провайдеру	Да: возвращённый контекст объединяется с текущим
После(Данные, Детали, Подсказки)	При успешной оценке	Нет
ПриОшибке(Данные, Ошибка, Подсказки)	При неудачной оценке	Нет
Финально(Данные, Детали, Подсказки)	Всегда, последней	Нет

Стадия До выполняется от глобальных хуков к локальным, остальные - в обратном порядке. Хуки накапливаются с трёх уровней: API, клиент, отдельный вызов.

8. Примеры

Файл	Что показывает
examples/БазоваяОценка.os	InMemoryProvider, четыре типа значений, детали и коды ошибок
examples/ТаргетингИВарианты.os	Варианты, правила таргетинга, приоритет контекстов
examples/ФлагиИзФайла.os	JsonFileProvider, перечитывание, испорченный файл
examples/Хуки.os	Четыре стадии, дополнение контекста, накопление хуков

Каждый пример запускается из корня проекта:

oscript examples/БазоваяОценка.os