Чем флаг отличается от конфига, ветки и эксперимента

Конфигурация окружения отвечает на вопрос «какой URL базы и какой таймаут». Она меняется редко, часто требует перезапуска и не рассчитана на персонализацию по пользователю. Ветка в системе контроля версий отвечает на вопрос «какой код мы собрали»; чтобы «выключить» ветку после деплоя, нужен откат или срочный фикс. Эксперимент (A/B) отвечает на вопрос «какой вариант лучше по метрике» — у него есть гипотеза, размер выборки и дата остановки.

Флаг функций отвечает на вопрос «какое поведение сейчас разрешено для этого контекста». Контекст обычно включает идентификатор пользователя или устройства, арендатора, план подписки, гео, версию клиента и атрибуты сегмента. Один и тот же ключ флага может обслуживать несколько сценариев: скрытый запуск (код пишет в тень, UI не меняется), канареечный процент, белый список внутренних аккаунтов, аварийный выключатель платежного модуля.

Практическое различие видно в инциденте. Если новая проверка подписи сломала вход, откат контейнера занимает минуты и рискует откатить чужие исправления. Выключение флага auth_v2_verify занимает секунды и оставляет остальной релиз на месте. Если же «флаг» живёт только как переменная окружения без сегментов — вы снова в мире бинарного переключателя на всё окружение сразу.

Модель оценки: ключ, контекст, правила, значение по умолчанию

Любая зрелая система флагов сводится к одной функции: (ключ, контекст, окружение) → значение. Значение бывает булевым, строковым, числовым или структурированным JSON — но команда должна заранее договориться, что «выключено» означает на каждом слое.

Ключ флага — стабильный идентификатор в коде (checkout_express_v1), а не маркетинговое название кнопки. Контекст — набор атрибутов, которые правила имеют право читать: userId, accountId, plan, country, appVersion, employee. Правила — упорядоченный список условий с приоритетом: сначала внутренние аккаунты, потом белый список клиентов, потом процент, потом значение по умолчанию. Окружение (dev / staging / prod) отделяет эксперименты от продакшена: один ключ, разные таблицы правил.

Важный инвариант: значение по умолчанию должно быть безопасным при недоступности сервиса флагов. Если SDK не достучался до удалённого конфига, приложение не должно «случайно» включить оплату в новой схеме. Обычно безопасный запасной вариант — старое поведение. Исключение — аварийный выключатель: при сомнении в целостности платежей разумнее отказать в рискованной операции, чем продолжать на полусломанной ветке. Эти два режима нужно явно различать в коде: failOpen vs failClosed.

`ts type FlagValue = boolean | string | number | Record<string, unknown>;

type EvaluationContext = { targetingKey: string; // стабильный id для закреплённости attributes: Record<string, string | number | boolean>; };

function evaluate( key: string, ctx: EvaluationContext, запасной вариант: FlagValue, ): FlagValue { // 1) локальный снимок правил // 2) match по приоритету // 3) процент от hash(targetingKey + key + salt) // 4) иначе запасной вариант return запасной вариант; } `

Закреплённость и процентная раскатка

«Включить для 10% пользователей» без закреплённости превращает продукт в лотерею: при каждом запросе человек может попасть в другую ветку. Это ломает кэш, аналитику, поддержку и доверие. Закреплённость (закреплённость) означает: для данного targetingKey и ключа флага результат процентного правила стабилен, пока не сменится соль или порог.

Классическая схема — взять криптографически приемлемый хеш от targetingKey + flagKey + salt, привести к числу 0…99 или 0…9999 и сравнить с порогом. Соль нужна, чтобы один и тот же пользователь не попадал в одни и те же «первые 10%» по всем флагам сразу (иначе канарейка всегда бьёт по одной когорте). Когда поднимаете порог с 10% до 25%, уже попавшие остаются внутри; новые добираются из оставшихся.

Отдельно решите, что является targetingKey. Для B2B часто нужен accountId: весь тенант видит одно поведение, иначе поддержка не сможет объяснить клиенту «у коллеги кнопка есть, у вас нет». Для потребительского UI — userId. Для анонимов до логина — стабильный cookie устройства, с явной миграцией на userId после входа (иначе человек «потеряет» новую корзину при авторизации).

Где оценивать: сервер, край, клиент

Серверная оценка — источник истины для авторизации, биллинга, записи данных и всего, что нельзя доверить браузеру. Клиент получает уже принятое решение или подписанный снимок булевых флагов для UI. Край (edge / BFF) удобен, когда нужно менять HTML или заголовки до гидрации без раскрытия внутренних правил.

Клиентская оценка соблазнительна скоростью: SDK подтянул JSON правил и решает локально. Цена — утечка логики сегментов, рассинхрон с сервером и возможность подделать ответ в DevTools. Допустимо для косметики («показать баннер»), недопустимо как единственная проверка «можно ли вызвать дорогой API». Паттерн, который переживает прод: сервер оценивает и кладёт результат в сессию или короткий подписанный пакет; клиент только отображает.

Связка с офлайн-сценариями требует дисциплины. Если приложение пишет действия в outbox, как в разборе офлайн-режима в React, флаг на момент постановки в очередь может отличаться от флага на момент доставки. Либо фиксируйте версию поведения вместе с событием, либо делайте сервер идемпотентным к обеим схемам на переходный период.

Для стека LLM флаги особенно полезны как маршрутизация: какая модель, какой лимит токенов, включён ли семантический кэш. Это хорошо стыкуется с идеями шлюза LLM и финансовой дисциплины — бюджет и качество меняются без деплоя, но с аудитом «кто включил дорогую модель для сегмента».

Аварийный выключатель, скрытый запуск и канарейка

Три паттерна часто путают под одним словом «флаг».

Аварийный выключатель (kill switch) — булев рычаг «выключить опасную подсистему сейчас». Он должен быть отдельным ключом с failClosed для рискованных операций, доступным дежурному без прохождения полной процедуры изменений на ночном инциденте. Документируйте, что именно отключается: приём платежей, генерация отчётов, запись в новую таблицу.

Скрытый запуск (dark launch) — новый код выполняется в тени: считает, пишет в лог, сравнивает с старым путём, но не влияет на ответ пользователю. Флаг здесь включает нагрузку и сбор расхождений. Это дешевле полного A/B, если цель — уверенность в корректности, а не измерение конверсии.

Канареечный выпуск — малый процент или сегмент видит новое поведение по-настоящему. Здесь нужны метрики и стоп-условия: рост 5xx, рост латентности p95, рост обращений в поддержку. Без заранее описанного «когда откатываем флаг» канарейка превращается в надежду.

Связка с качеством: флаг не отменяет тесты. Он снижает радиус поражения, пока экономика ошибок всё ещё требует пирамиды проверок на оба пути. Минимум — юнит-тесты на обе ветки и контрактный тест, что сервер и клиент читают один ключ.

Жизненный цикл флага и налог на сложность

Самая дорогая часть флагов — не SDK, а ветвления, которые никто не удалил. Через полгода if (flag) размножается в сервисах, мобильных клиентах и отчётах. Команда боится трогать «временный» код, потому что неясно, кто ещё зависит от выключенного состояния.

Рабочий ритуал:

1. При создании флага указать владельца, цель, окружения, безопасный запасной вариант и дату пересмотра.
2. После полного раската (100% + стабильность) завести задачу на удаление мёртвой ветки и самого ключа.
3. Раз в спринт прогонять отчёт «флаги старше N дней в состоянии 100% или 0%».
4. Запретить новые зависимости от флага, помеченного retired.

Именование помогает автоматизации: exp_ для экспериментов, ops_ для аварийных выключателей, perm_ для долгосрочных флагов прав тарифа (план Pro видит модуль). Смешивать их в одном реестре без префикса — путь к путанице прав доступа и маркетинговых тестов.

Долгосрочные флаги допустимы, но это уже продуктовая конфигурация прав, а не «временная раскатка». Их стоит вести рядом с биллингом и ACL, с аудитом изменений и без права у дежурного случайно выключить оплату всей Европе.

OpenFeature, свои правила и выбор провайдера

OpenFeature стандартизирует API оценки в приложении: вы пишете против абстракции, а провайдер (Unleash, Flagsmith, LaunchDarkly, домашний Redis+JSON) подключается сбоку. Выгода — смена вендора без переписывания сотен if. Невыгода — всё равно нужно спроектировать модель контекста, сегменты и наблюдаемость.

Свой лёгкий движок оправдан, если правил мало, команда маленькая и требования к аудиту скромные. Как только появляются сложные сегменты, проценты, мультирегион, права на изменение флагов и история «кто включил в 03:00» — стоимость самописного админ-UI обычно превышает лицензию или на своей инфраструктуре Unleash.

Критерии выбора, которые реально бьют по боли:

• задержка распространения правил (секунды vs минуты);
• поддержка серверных и клиентских SDK с одним контрактом ключей;
• аудит и RBAC на изменение флагов;
• экспорт событий оценки в вашу аналитику (без этого A/B врёт);
• поведение при сетевом разделении и размер локального снимка правил.

Не тащите в клиентский бандл полную карту сегментов с PII. Отдавайте уже вычисленные значения или минимизированные правила без внутренних комментариев вроде «VIP из сделки #4821».

Безопасность, мультиарендность и утечки

Флаг, который открывает админ-API только по клиентской проверке, — дыра. Флаг, который включает чужие данные тенанта при ошибке в сегменте, — инцидент уровня GDPR. Правила сегментов должны опираться на атрибуты, которые сервер уже доверяет (из сессии после проверки JWT, из claims IdP), а не на параметр запроса ?vip=1.

Мультитенантность: никогда не оценивайте флаг «глобально включён» там, где нужен периметр арендатора. Либо контекст всегда содержит tenantId, либо отдельные ключи на контур. Логи оценки не должны писать секреты и полные персональные данные — достаточно хеша ключа таргетинга и имени флага.

Цепочка поставок тоже касается флагов: админка с слабым входом — способ выключить защиту или включить отладочный режим для всех. Относитесь к системе флагов как к критичному плоскость управления: SSO, короткий TTL сессии, журнал изменений, запрет анонимного API записи.

Наблюдаемость и критерии раскатки

Без метрик флаг — религия. Минимальный набор: счётчик оценок по ключу и значению, ошибка SDK, задержка синхронизации снимка, бизнес-метрики сегмента «включено» vs «выключено». При канарейке заранее зафиксируйте пороги отката и владельца решения.

Полезно логировать flagKey, value, reason (targeting_match, percentage, default, error) в структурированном виде — это ускоряет разбор «почему у клиента старый интерфейс». Не логируйте каждый запрос на горячем пути без семплирования: оценка флагов часто вызывается десятки раз на страницу.

Связка с агентным кодом: если ИИ-агент меняет поведение через флаги, нужен тот же аудит, что и для людей — тема агентной инженерии прямо про управляемые изменения без потери качества. Автоматическое «включить на 100% после зелёных тестов» допустимо только с жёсткими стоп-метками по продакшен-сигналам.

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

Один флаг на пять несвязанных изменений

Трудно откатить «половину». Дробите по продуктовому смыслу: UI корзины отдельно от пересчёта налогов.

Клиент включил, сервер выключил

Пользователь видит кнопку и получает 403. Всегда один ключ и одна серверная проверка на мутацию.

Процент от Math.random()

Нет закреплённости — нет аналитики и поддержки.

Флаг в коде без записи в реестре

«Призраки» невозможно вычистить. Реестр (хотя бы таблица в том же Unleash) обязан быть источником имён.

Вечный эксперимент

A/B без даты остановки и без решения «какой вариант оставить» превращается в постоянное удвоение путей.

Секреты и URL только за флагом на клиенте

Всё, что попало в бандл, можно прочитать. Секреты — на сервере; флаг лишь решает, вызывать ли API.

Минимальный каркас в продукте

1. Выберите провайдера или тонкий слой поверх Redis с версионированным снимком правил.
2. Введите OpenFeature (или свой фасад) в BFF и воркерах; запретите прямой доступ к вендор-SDK из фич-модулей.
3. Определите стандарт контекста: targetingKey, tenantId, plan, appVersion.
4. Для каждого нового флага заполните карточку: владелец, запасной вариант, тип (ops / exp / perm), дата пересмотра.
5. На канарейке подключите дашборд с порогом отката.
6. После 100% удалите мёртвую ветку в том же эпике, что и «закрытие раскатки».

Этого достаточно, чтобы флаги стали инструментом снижения риска, а не складом условных операторов. Набор технологий фронтенда при этом может оставаться любым из карты React 2026 — меняется дисциплина поставки, а не выбор UI-библиотеки.

Частые вопросы

Заключение

Флаги функций переносят момент решения «включить поведение» из деплоя в рантайм — и только тогда окупаются, когда оценка серверная для критичных путей, процент закреплён, у ключа есть владелец и дата снятия, а админка защищена как плоскость управления. Без этого вы покупаете скорость релиза ценой второго легаси внутри каждого if.

Читать дальше

• Почему дешёвое тестирование обходится дорого
• Шлюз LLM и финансовая операционная дисциплина в 2026
• Офлайн-режим в React: запись, которая доживает до сервера
• Агентная инженерия в 2026 году
• JWT в Node.js: пять ошибок, которые ломают API
• React 2026: карта библиотек по категориям
• Ключи доступа и WebAuthn в продакшене