Обзор SDK

SDK можно. — это клиентские библиотеки, которые загружают правила с сервера и локально оценивают фиче-флаги в вашем приложении.

Архитектура

graph TD
    subgraph "Ваше приложение"
        SDK[SDK mozhno]
        EVAL[Локальная оценка]
        CACHE[Кеш правил]
    end
    subgraph "Сервер mozhno"
        API[REST API]
        DB[(PostgreSQL)]
    end

    SDK -->|1. Загрузка правил| API
    API -->|2. Правила| SDK
    SDK -->|3. Сохраняет| CACHE
    SDK -->|4. Оценивает локально| EVAL
    SDK -->|5. Фоновый поллинг| API
    APP[Код приложения] -->|isEnabled?| SDK
    SDK -->|true/false| APP

Принцип локальной оценки

Старт: SDK загружает все правила флагов с сервера один раз.
Кеширование: Правила сохраняются в памяти.
Локальная оценка: Каждый вызов isEnabled() оценивается локально — без задержки сети.
Фоновое обновление: SDK периодически опрашивает сервер (по умолчанию каждые 15 секунд) и обновляет кеш. Используется ETag / If-None-Match для эффективных дельта-обновлений.

Преимущество	Описание
Нулевая задержка	Оценка флага: доли микросекунды
Нет single point of failure	Если сервер недоступен, SDK продолжает работать с закешированными правилами
Масштабируемость	Сервер не нагружается запросами оценки флагов

Логика оценки

SDK оценивает флаг в следующем порядке:

Флаг выключен? → false
Нет стратегии/activation? → true
Ограничения (constraints): все правила должны совпасть с контекстом (И)
Сегменты: хотя бы один сегмент должен совпасть (ИЛИ)
Если есть и то, и другое: достаточно совпадения одного (ИЛИ)
Процентный роллаут: MurmurHash32 от flagKey + (userId || sessionId), сравнение с процентом
Ничего не совпало → false

Поддерживаемые операторы

Оператор	Описание
`in`	Значение входит в список
`not_in`	Значение не входит в список
`eq`	Равенство (числовое для `contextType: number`)
`ne`	Неравенство
`gt`	Больше
`gte`	Больше или равно
`lt`	Меньше
`lte`	Меньше или равно
`contains`	Подстрока

Типы контекста

Тип	Поведение
`string` (по умолчанию)	Строковое сравнение
`number`	Числовое сравнение
`time`	Сравнение ISO8601 дат
`semver`	Семантическое версионирование

Синхронизация правил

SDK использует механизм Polling (периодический опрос). Интервал по умолчанию — 15 секунд.

sequenceDiagram
    participant SDK
    participant Server

    SDK->>Server: GET /api/client/features (If-None-Match)
    Server-->>SDK: 200 + JSON (или 304 Not Modified)
    Note over SDK: Кеширование в памяти

    loop Каждые 15 секунд
        SDK->>Server: GET /api/client/features (If-None-Match)
        Server-->>SDK: 304 Not Modified (или обновлённые флаги)
        Note over SDK: Атомарное обновление кеша
    end

Параметр	Значение по умолчанию	Описание
Интервал опроса	15 секунд	`refreshInterval` (JS) / `fetchTogglesInterval` (Java)
Retry при ошибке	Экспоненциальный backoff	1с → 2с → 4с
Circuit breaker (Java)	5 ошибок → 60с пауза	Защита от перегрузки сервера

Инициализация клиента

Java SDK

java

MozhnoConfig config = MozhnoConfig.builder()
    .appName("my-app")
    .instanceId("instance-1")
    .mozhnoUrl("http://localhost:8080")
    .apiKey("<api-key>")
    .fetchTogglesInterval(15)
    .sendMetricsInterval(60)
    .environment("production")
    .build();

MozhnoClient client = new DefaultMozhnoClient(config);
client.start();
boolean enabled = client.isEnabled("new-checkout", context);

JavaScript / TypeScript SDK

typescript

import { MozhnoClient } from '@mozhno/client-js';

const client = new MozhnoClient({
  url: 'http://localhost:8080',
  apiKey: '<api-key>',
  appName: 'my-app',
  refreshInterval: 15,
  metricsInterval: 60,
  environment: 'production',
});

await client.start();
const enabled = client.isEnabled('new-checkout', { userId: 'user-123' });

Общие параметры конфигурации

Параметр	JS ключ	Java ключ	По умолчанию	Описание
URL сервера	`url`	`mozhnoUrl`	Обязательно	Базовый URL сервера
API-ключ	`apiKey`	`apiKey`	Обязательно	API-ключ окружения
Имя приложения	`appName`	`appName`	Обязательно	Идентификатор приложения
ID экземпляра	`instanceId`	`instanceId`	Обязательно (Java)	Уникальный ID инстанса
Интервал опроса (с)	`refreshInterval`	`fetchTogglesInterval`	`15`	Частота поллинга
Интервал метрик (с)	`metricsInterval`	`sendMetricsInterval`	`60`	Частота отправки метрик
Окружение	`environment`	`environment`	`null` (Java) / `"default"` (JS)	Имя окружения
Отключить метрики	`disableMetrics`	`disableMetrics`	`false`	Отключение метрик

Контекст оценки

Контекст — это map атрибутов, описывающих текущий запрос или пользователя:

java

MozhnoContext context = MozhnoContext.builder()
    .userId("user-123")
    .sessionId("session-abc")
    .addProperty("country", "RU")
    .addProperty("plan", "premium")
    .build();

typescript

const context = {
  userId: 'user-123',
  sessionId: 'session-abc',
  country: 'RU',
  plan: 'premium',
};

Обработка ошибок и отказоустойчивость

Запуск SDK

Ситуация	Java SDK	JS SDK
Сервер доступен при старте	Загружает правила, клиент готов	Загружает правила, клиент готов
Сервер недоступен при старте	Выбрасывает исключение при `synchronousFetchOnInitialisation(true)`. Иначе — запускается и ретраит в фоне	Promise отклоняется
Сервер стал недоступен в работе	Используется закешированное состояние. Фоновые ретраи	Используется закешированное состояние. Фоновые ретраи

Совет: В продакшене используйте synchronousFetchOnInitialisation(false) (по умолчанию) — SDK запустится даже если сервер временно недоступен при старте, и догонит правила при восстановлении связи.

Оценка флагов

Ситуация	Поведение
Флаг не найден	Возвращается `false` (fail-closed)
Флаг найден, кеш пуст	Возвращается `false` — безопасное поведение по умолчанию
Атрибут отсутствует в контексте	Правило с этим атрибутом возвращает `false`
Сеть недоступна	Закешированные правила продолжают работать

Задержка обновлений

Изменения флага в веб-панели доходят до SDK за время polling-интервала (по умолчанию 15 секунд).

Поддерживаемые SDK

Язык	Пакет	Документация
Java	`dev.mozhno:mozhno-client-java` (Gradle)	Java SDK
JavaScript / TypeScript	`@mozhno/client-js` (npm)	JS SDK

Что дальше?

Java SDK — установка, конфигурация и API для Java
JavaScript / TypeScript SDK — установка и интеграция с React
Быстрый старт — создание первого флага
REST API — прямое взаимодействие с API сервера

Обзор SDK ​

Архитектура ​

Принцип локальной оценки ​

Логика оценки ​

Поддерживаемые операторы ​

Типы контекста ​

Синхронизация правил ​

Инициализация клиента ​

Java SDK ​

JavaScript / TypeScript SDK ​

Общие параметры конфигурации ​

Контекст оценки ​

Обработка ошибок и отказоустойчивость ​

Запуск SDK ​

Оценка флагов ​

Задержка обновлений ​

Поддерживаемые SDK ​

Что дальше? ​