Оглавление

• Зачем бизнесу фича‑флаги
• Где флаги действительно нужны, а где нет
• Архитектура флагов: от простого к надёжному
• Типы флагов и как ими управлять
• Процентные выкладки без сюрпризов (стабильное распределение)
• Пример: минимальная библиотека флагов на TypeScript
• Безопасность, права и аудит
• Наблюдаемость: метрики, алёрты, связь с конверсией
• Производительность и отказоустойчивость
• Процессы: жизнь флага от идеи до удаления
• Частые ошибки и как их избежать
• Чек-лист внедрения за 2 недели
• Выводы

Зачем бизнесу фича‑флаги

Фича‑флаги — это управляемые переключатели в коде, которые позволяют включать/выключать функциональность без нового деплоя. Бизнес‑выгоды:

• Быстрее релизы. Вы выкладываете код заранее, а включаете функцию, когда готовы. Никаких «ночных релизов» ради одного переключателя.
• Меньше рисков. Если метрики падают, достаточно выключить флаг за секунды — без отката артефактов.
• Эксперименты. Проще проверять гипотезы: включить 5% аудитории, сравнить конверсию, расширять до 50% и т. д.
• Управление нагрузкой. Постепенно увеличиваете долю пользователей и наблюдаете, как ведут себя базы, кэши и очереди.
• Легче согласования. Бизнес и продукт сами управляют флагами в интерфейсе, а разработчики не стоят «на телефоне».

Где флаги действительно нужны, а где нет

Нужны:

• Важно быстро отключить рискованный кусок (новый метод оплаты, новый поиск, новая рекомендационная модель).
• Нужна поэтапная выкладка (сначала сотрудники, затем 1%, 10%, 25%, 50%, 100%).
• Нужны A/B‑тесты и таргетирование (по стране, платформе, сегменту).

Не нужны:

• Постоянная конфигурация окружения (URLs, креды) — это не флаги, а настройки.
• Технический долг «навсегда». Флаг — временный инструмент. Его нужно удалить после принятия решения.
• Управление безопасностью на проде «на лету», если у вас нет процесса и аудита. Тогда лучше роль‑модель и права.

Архитектура флагов: от простого к надёжному

Минимальный вариант:

• Хранение в Git (JSON/YAML), сервис периодически подтягивает файл, кеширует в памяти.
• Оценка правил (evaluation) локально, без сетевых запросов на каждый HTTP‑запрос.

Более надёжный вариант:

• Централизованное хранилище флагов (PostgreSQL/Redis/специализированный сервис).
• Клиент‑SDK в каждом сервисе: держит локальный кеш, получает обновления по пуллу (ETag/If-None-Match) или пушу (веб‑сокет/стрим).
• Подпись/проверка конфигурации (HMAC) для защиты от подмены.
• Аудит: кто, когда, что включил, с комментариями и связью с задачей/тикетом.

Доставлять флаги можно двумя способами:

• Pull: сервис опрашивает конфиг раз в N секунд и получает 304 Not Modified через ETag. Просто и надёжно.
• Push: сервер шлёт обновления при изменении. Быстро, но сложнее и требует внимательности к отказам.

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

Типы флагов и как ими управлять

• Релиз‑флаг. Управляет выпуском новой функции. Временный, с чёткой датой удаления.
• Экспериментальный. Несколько вариантов (A/B/n), используется с аналитикой. Тоже временный.
• Операционный (kill‑switch). Мгновенно выключает рискованный путь (например, интеграцию). Может жить долго, но должен быть документирован и протестирован.
• Флаг разрешений. Включает модуль по лицензии/тарифу. Постоянный, но «закостеневать» в бизнес‑логике нельзя: оставляйте один слой принятия решения и покрывайте тестами.

У каждого флага должны быть владелец, цель, план запуска, критерии успеха/отката и срок удаления.

Процентные выкладки без сюрпризов (стабильное распределение)

Чтобы один и тот же пользователь стабильно попадал в одну группу, используйте детерминированное хэширование (salt + userId → число 0..100). Тогда при 10% включения одни и те же люди будут видеть функцию до тех пор, пока процент не изменится.

Лучшие практики:

• «Липкая» привязка к ключу пользователя (userId, deviceId, cookie). Для неавторизованных — генерируйте анонимный идентификатор и храните в куке.
• Отдельная «соль» на каждый флаг, чтобы сегменты не пересекались случайно.
• Изменение процентов — ступенчато и с паузами для наблюдения метрик.

Пример: минимальная библиотека флагов на TypeScript

Ниже — полностью рабочий пример. Он:

• Загружает флаги из локального JSON‑файла (просто для демонстрации; в проде читайте из БД/HTTP с кешем).
• Оценивает правила локально: по проценту, стране, платформе, спискам пользователей.
• Обеспечивает стабильное распределение через SHA‑256.

// file: featureFlags.ts
// Требуется Node.js 18+ (для fs/promises и встроенного fetch, хотя тут сеть не используется)

import { createHash } from 'node:crypto'
import { readFile } from 'node:fs/promises'
import { watch } from 'node:fs'

// Типы конфигурации флагов
export type Context = {
  userId?: string
  country?: string
  platform?: 'ios' | 'android' | 'web' | string
  [key: string]: unknown
}

type PercentRule = { userIdPercent: { salt: string; percent: number } }
type CountryInRule = { countryIn: string[] }
type PlatformInRule = { platformIn: string[] }
type UserInRule = { userIdIn: string[] }

type Condition = PercentRule | CountryInRule | PlatformInRule | UserInRule

export type FlagRule = {
  if: Condition
  value: boolean | string | number
}

export type FlagDefinition = {
  type: 'boolean' | 'string' | 'number'
  default: boolean | string | number
  rules?: FlagRule[]
  description?: string
}

export type FlagsConfig = {
  flags: Record<string, FlagDefinition>
  version?: string
}

// Хэш → процент 0..100 (детерминированно и стабильно)
function percentForKey(key: string): number {
  const h = createHash('sha256').update(key).digest()
  // Берём первые 4 байта как беззнаковое 32‑битное число
  const value = h.readUInt32BE(0)
  return (value / 0xffffffff) * 100
}

function matches(cond: Condition, ctx: Context): boolean {
  if ('userIdPercent' in cond) {
    const { salt, percent } = cond.userIdPercent
    const id = ctx.userId ?? ''
    const p = percentForKey(`${salt}:${id}`)
    return p < percent
  }
  if ('countryIn' in cond) {
    if (!ctx.country) return false
    return cond.countryIn.includes(String(ctx.country).toUpperCase())
  }
  if ('platformIn' in cond) {
    if (!ctx.platform) return false
    return cond.platformIn.includes(String(ctx.platform).toLowerCase())
  }
  if ('userIdIn' in cond) {
    if (!ctx.userId) return false
    return cond.userIdIn.includes(ctx.userId)
  }
  return false
}

export class FlagStore {
  private config: FlagsConfig = { flags: {} }
  private readonly filePath: string
  private lastLoadedAt: number = 0

  constructor(filePath: string) {
    this.filePath = filePath
  }

  async load(): Promise<void> {
    const raw = await readFile(this.filePath, 'utf8')
    const parsed = JSON.parse(raw) as FlagsConfig
    this.validate(parsed)
    this.config = parsed
    this.lastLoadedAt = Date.now()
  }

  watch(): void {
    // Перезагружаем конфиг при изменениях файла (с защитой от дребезга)
    let timer: NodeJS.Timeout | null = null
    watch(this.filePath, { persistent: false }, () => {
      if (timer) clearTimeout(timer)
      timer = setTimeout(() => this.load().catch(console.error), 100)
    })
  }

  getConfig(): FlagsConfig {
    return this.config
  }

  private validate(cfg: FlagsConfig) {
    for (const [key, def] of Object.entries(cfg.flags)) {
      if (!['boolean', 'string', 'number'].includes(def.type)) {
        throw new Error(`Флаг ${key}: неизвестный тип ${String(def.type)}`)
      }
      if (def.rules) {
        for (const r of def.rules) {
          if (!('if' in r) || typeof r.if !== 'object') {
            throw new Error(`Флаг ${key}: некорректное правило`)
          }
        }
      }
    }
  }
}

export class FlagEvaluator {
  constructor(private readonly store: FlagStore) {}

  // Универсальная оценка
  eval<T extends boolean | string | number>(flagKey: string, ctx: Context): T | undefined {
    const def = this.store.getConfig().flags[flagKey]
    if (!def) return undefined
    if (!def.rules || def.rules.length === 0) return def.default as T
    for (const rule of def.rules) {
      if (matches(rule.if, ctx)) return rule.value as T
    }
    return def.default as T
  }

  // Удобные шорткаты
  isOn(flagKey: string, ctx: Context): boolean {
    const v = this.eval<boolean>(flagKey, ctx)
    return Boolean(v)
  }
}

// Пример использования
// 1) Создайте файл flags.json и положите туда конфиг (см. ниже)
// 2) Запустите этот модуль как скрипт: `node --loader ts-node/esm featureFlags.ts` или соберите с tsc

if (require.main === module) {
  ;(async () => {
    const store = new FlagStore('./flags.json')
    await store.load()
    store.watch()

    const evalr = new FlagEvaluator(store)

    const ctxIvan: Context = { userId: 'u123', country: 'RU', platform: 'web' }
    const ctxAnna: Context = { userId: 'u777', country: 'KZ', platform: 'ios' }

    console.log('new_checkout for Ivan:', evalr.isOn('new_checkout', ctxIvan))
    console.log('new_checkout for Anna:', evalr.isOn('new_checkout', ctxAnna))
  })().catch((e) => {
    console.error(e)
    process.exit(1)
  })
}

Пример конфигурации флагов (файл flags.json):

{
  "version": "2026-02-01",
  "flags": {
    "new_checkout": {
      "type": "boolean",
      "default": false,
      "description": "Новый процесс оплаты",
      "rules": [
        { "if": { "userIdIn": ["admin", "qa1", "qa2"] }, "value": true },
        { "if": { "countryIn": ["RU", "KZ"] }, "value": true },
        { "if": { "userIdPercent": { "salt": "checkout_v1", "percent": 10 } }, "value": true }
      ]
    },
    "recommendation_model": {
      "type": "string",
      "default": "v1",
      "description": "Модель рекомендаций",
      "rules": [
        { "if": { "platformIn": ["ios"] }, "value": "v2" }
      ]
    },
    "rating_weight": {
      "type": "number",
      "default": 1.0,
      "description": "Вес рейтинга для сортировки",
      "rules": [
        { "if": { "userIdPercent": { "salt": "rank_weight", "percent": 5 } }, "value": 1.2 }
      ]
    }
  }
}

Как это использовать в веб‑приложении:

• Загружаете конфиг при старте, включаете наблюдение или периодическую перезагрузку.
• В обработчике запроса собираете контекст (userId, страна, платформа), вызываете evaluator и принимаете решение.
• Метки (например, какую ветку UI отрендерили) — отправляете в аналитику.

Безопасность, права и аудит

• Роли и согласования. Изменение флага на проде должно быть доступно ограниченному кругу людей, с обязательным комментарием и связью с задачей.
• Подпись конфигурации. Если доставляете флаги по сети, подписывайте конфиг HMAC и проверяйте подпись на клиенте.
• Разделение обязанностей. Кто пишет код — не обязательно тот, кто включает флаг на 100%.
• Аудит и журнал событий. Кто включил, когда, с каким эффектом (ссылки на графики). Это критично при разборе инцидентов.

Наблюдаемость: метрики, алёрты, связь с конверсией

Минимальный набор метрик:

• Экспозиции флага (сколько запросов прошло с value=true/false/variant).
• Ошибки/латентность по сегментам (видит ли новая ветка рост 5xx/времени ответа?).
• Бизнес‑метрики по сегментам: конверсия, средний чек, удержание.

Алёрты:

• Если ошибка/латентность у сегмента с новым флагом на X% выше базовой — уведомление и автопонижение процента или выключение.
• Если экспозиций нет — возможно, флаг не подключен в нужных местах.

Производительность и отказоустойчивость

• Локальная оценка. На каждый запрос не ходим в сеть. Конфиг — в памяти, обновление — асинхронно.
• Таймауты и резерв. Если конфиг недоступен, используем последний успешный или дефолт. Выберите стратегию: fail‑open (оставить включённым) или fail‑closed (выключить), зафиксируйте её в документации.
• Кеширование на минуту/пять минут — достаточно. Для «красной кнопки» можно реализовать принудительную синхронизацию.
• Нагрузка на память невелика: сотни флагов — считанные мегабайты.

Процессы: жизнь флага от идеи до удаления

1. Идея: описание цели, метрик успеха, рисков, плана выкладки (ступени: 1% → 5% → 25% → 50% → 100%).
2. Реализация: один слой принятия решения, минимальная ветвистость кода, логирование факта срабатывания.
3. Запуск: сначала «внутренние» пользователи, затем маленький процент.
4. Наблюдение: 30–120 минут на каждой ступени, проверка метрик и логов.
5. Итог: либо 100% и план удаления флага из кода, либо откат и пост‑морем.
6. Удаление: в течение 1–2 спринтов. Автоматические напоминания по срокам TTL.

Частые ошибки и как их избежать

• Ветка за веткой. Слишком много условий вокруг флага. Решение: инкапсулируйте принятие решения в один метод и вызывайте его из UI/сервиса.
• Вечные флаги. Они превращаются в техдолг и усложняют сопровождение. Решение: TTL и «владельцы», регулярная уборка.
• Нестабильные проценты. Пользователь то в группе, то нет. Решение: детерминированный хэш с солью.
• Сетевые вызовы на каждый запрос. Решение: локальный кеш и асинхронная подтяжка конфига.
• Нет аудита. Невозможно понять, кто включил флаг перед инцидентом. Решение: протоколирование всех изменений с комментариями.
• Смешение флагов и настроек. Конфиги окружений храните отдельно, флаги — отдельно.

Чек-лист внедрения за 2 недели

День 1–2:

• Определите владельцев, процессы, роли.
• Выберите «склад» флагов: на старте достаточно JSON в Git.

День 3–5:

• Внедрите клиент‑SDK в 1–2 сервисах (по образцу из примера), добавьте метрики экспозиций.
• Настройте перезагрузку конфига и алёрты при ошибках.

День 6–8:

• Протяните первую реальную фичу с поэтапной выкладкой (внутренние → 1% → 5%).
• Добавьте журнал изменений (хотя бы в Git + описание в MR).

День 9–10:

• Включите бизнес‑метрики по сегментам, обсудите критерии успеха.

День 11–14:

• Документация: шаблон карточки флага (цель, метрики, владелец, план, дата удаления).
• Запланируйте уборку флагов раз в спринт, заведите напоминания по TTL.

Выводы

Фича‑флаги — простой способ ускорить релизы и снизить стоимость ошибок. Они работают, только если у вас есть:

• Локальная, быстрая оценка правил и надёжная доставка конфигурации;
• Процессы: владелец, аудит, метрики, план выкладки и удаления;
• Дисциплина в коде: минимальные ветвления, явные дефолты, тесты.

Начните с маленького: один флаг, один сервис, одна фича. Через пару недель вы увидите, что релизы стали спокойнее, а эксперименты — дешевле. Дальше можно добавлять пуш‑обновления, подписи конфигов, интерфейс для продукта и автоматические «красные кнопки».