Оглавление

• Зачем бизнесу фича‑флаги
• Типы флагов и когда их использовать
• Поэтапные выкаты: стратегии и сценарии
• Архитектура простой и надёжной системы флагов
• Рабочий пример на TypeScript/Node.js
• Фронт и мобильные клиенты: синхронизация и кэширование
• Безопасность, аудит и доступы
• Жизненный цикл флага и «долг»
• Метрики успеха и расчёт выгоды
• План внедрения за 4 недели
• Частые ошибки и как их избежать
• Чек‑лист для команды
• Итоги

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

Релизы «всё и сразу» — главный источник нервов, ночных выкладок и откатов. Фича‑флаги (переключатели фич) позволяют отделить выкладку кода от включения фичи для пользователей. Вы можете:

• выкатывать новый код заранее, но включать его только для 1–5% аудитории;
• быстро отключать проблемную фичу «рубильником», не трогая деплой и базу;
• делать эксперименты (A/B) без форков кода и веток, которые живут месяцами;
• раскатывать изменения по сегментам: страна, тариф, платная/бесплатная версия, канал привлечения и т. п.

В числах это обычно означает: меньше откатов и инцидентов, быстрее Time‑to‑Market, выше конверсия благодаря безопасным экспериментам.

Типы флагов и когда их использовать

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

Совет: не смешивайте роле‑базовые разрешения и разруливание инцидентов в одном флаге — иначе получите путаницу и риск ошибочного включения.

Поэтапные выкаты: стратегии и сценарии

• Процентная раскатка. Начните с 1%, затем 5%, 10%, 25%, 50%, 100%, контролируя метрики (ошибки, задержки, конверсию).
• Канареечные пользователи. Включайте флаг команде, внутренним пользователям, партнёрам. Быстрая обратная связь без риска.
• По признакам. География, платёжный план, устройство, версия приложения, канал привлечения.
• «Тёмный запуск». Код на проде, фича выключена. Нагрузочные проверки «в тени» без влияния на пользователей.
• Быстрый рубильник. Отключение фичи по одному переключателю за секунды — главный инструмент снижения убытков.

Антипаттерн: «включили на 100% и пошли спать». Между шагами давайте системе «устояться», наблюдайте графики: ошибки, 95/99‑перцентили задержек, целевые метрики бизнеса.

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

• Хранилище. Постоянное — база данных; быстрая доставка — кэш (например, в памяти процесса), плюс опционально Redis или другой брокер для рассылки обновлений.
• Клиентское ядро (SDK). Лёгкая библиотека, которая:
  • оценивает правила флага локально (без сетевых походов);
  • кэширует флаги с TTL и умеет получать обновления;
  • устойчиво работает, если сервер недоступен (фолбэк к последней версии).
• Формат флага. Ключ, значение по умолчанию, набор правил, условия, процентная раскатка, метаданные (создатель, срок жизни, теги).
• Доставка. Пуллинг с ETag/If‑None‑Match, длинные опросы или веб‑сокеты для редких обновлений. На сервер‑стороне — Pub/Sub для мгновенного фан‑аута.
• Наблюдаемость. Экспозиции флагов (кто и что увидел), обратная связь в метриках (ошибки, задержки), аудит изменений.

Принцип надёжности: «при отказе всё остаётся работать в безопасном состоянии». Значение по умолчанию и локальный кэш — обязательны.

Рабочий пример на TypeScript/Node.js

Ниже — минимальная, но рабочая реализация: сервер с флагами, локальная оценка правил, процентная раскатка по стабильному хэшу userId, API для управления и пример использования в маршруте. Код можно запускать как обычный Node‑сервис.

// file: server.ts
import express, { Request, Response, NextFunction } from 'express';
import crypto from 'crypto';

// --- Модель флага ---
interface Condition {
  attr: string;
  op: 'eq' | 'in';
  value: string | number | boolean | Array<string | number | boolean>;
}

interface Rule {
  match?: Condition[];             // условия применения правила
  percentage?: number;             // 0..100 — доля аудитории
  value: boolean;                  // значение флага, если правило сработало
}

interface Flag {
  key: string;
  enabled: boolean;                // глобальный рубильник флага
  defaultValue: boolean;           // значение по умолчанию
  rules: Rule[];                   // правила, применяются сверху вниз
  description?: string;
  owner?: string;
}

// --- Простое хранилище флагов в памяти ---
const flags = new Map<string, Flag>();

// Пример флага: поэтапный чекаут
flags.set('checkout.new', {
  key: 'checkout.new',
  enabled: true,
  defaultValue: false,
  description: 'Новый чекаут: сначала сотрудники и 10% пользователей PRO',
  owner: 'team-payments',
  rules: [
    // Внутренние пользователи (e-mail домена) — всегда включено
    {
      match: [{ attr: 'email', op: 'in', value: ['@company.com'] }],
      value: true,
    },
    // Для тарифа PRO — 10% по стабильному хэшу userId
    {
      match: [{ attr: 'plan', op: 'eq', value: 'pro' }],
      percentage: 10,
      value: true,
    },
  ],
});

// --- Оценка флага ---
function hashToPercent(seed: string): number {
  const h = crypto.createHash('sha1').update(seed).digest('hex').slice(0, 8);
  const n = parseInt(h, 16); // 0..2^32
  return (n % 100) + 1; // 1..100
}

function matchesCondition(ctx: Record<string, any>, c: Condition): boolean {
  const v = ctx[c.attr];
  if (c.op === 'eq') return v === c.value;
  if (c.op === 'in') {
    if (Array.isArray(c.value)) {
      return c.value.includes(v) || (typeof v === 'string' && c.value.some((x) => typeof x === 'string' && v.toString().includes(x as string)));
    }
    return typeof v === 'string' && typeof c.value === 'string' && v.includes(c.value);
  }
  return false;
}

function evaluateFlag(flag: Flag | undefined, ctx: Record<string, any>): boolean {
  if (!flag) return false; // безопасный дефолт
  if (!flag.enabled) return false; // глобально выключен

  for (const r of flag.rules) {
    if (r.match && !r.match.every((c) => matchesCondition(ctx, c))) {
      continue; // условия не подходят — к следующему правилу
    }

    if (r.percentage !== undefined) {
      const id = ctx.userId ?? ctx.sessionId ?? 'anonymous';
      const p = hashToPercent(String(id) + ':' + flag.key);
      if (p <= Math.max(0, Math.min(100, r.percentage))) {
        return r.value;
      }
      // процент не попал — продолжаем искать правило дальше
      continue;
    }

    return r.value; // правило сработало без процента
  }

  return flag.defaultValue;
}

// --- Расширяем Request, чтобы было удобно проверять флаги ---
declare global {
  // eslint-disable-next-line @typescript-eslint/no-namespace
  namespace Express {
    interface Request {
      feature: (key: string, ctx?: Record<string, any>) => boolean;
      user?: { id: string; email?: string; plan?: string };
    }
  }
}

const app = express();
app.use(express.json());

// Простая аутентификация-заглушка: вытаскиваем user из заголовков для примера
app.use((req: Request, _res: Response, next: NextFunction) => {
  const id = req.header('x-user-id') || 'anon';
  const email = req.header('x-user-email') || undefined;
  const plan = req.header('x-user-plan') || 'free';
  req.user = { id, email, plan };
  req.feature = (key: string, extraCtx: Record<string, any> = {}) => {
    const flag = flags.get(key);
    const ctx = {
      userId: req.user?.id,
      email: req.user?.email || '',
      plan: req.user?.plan || 'free',
      ...extraCtx,
    };
    return evaluateFlag(flag, ctx);
  };
  next();
});

// --- API для чтения и управления флагами ---
app.get('/flags', (_req, res) => {
  res.json(Array.from(flags.values()));
});

app.put('/flags/:key', (req, res) => {
  const key = req.params.key;
  const incoming = req.body as Partial<Flag> & { key?: string };
  const current = flags.get(key);
  const updated: Flag = {
    key,
    enabled: incoming.enabled ?? current?.enabled ?? true,
    defaultValue: incoming.defaultValue ?? current?.defaultValue ?? false,
    rules: incoming.rules ?? current?.rules ?? [],
    description: incoming.description ?? current?.description,
    owner: incoming.owner ?? current?.owner,
  };
  flags.set(key, updated);
  res.json(updated);
});

// --- Пример бизнес-маршрута: новый чекаут ---
app.get('/checkout', (req, res) => {
  const useNew = req.feature('checkout.new');
  if (useNew) {
    return res.json({ version: 'new', message: 'Новый чекаут активен' });
  }
  return res.json({ version: 'old', message: 'Старый чекаут' });
});

app.listen(3000, () => {
  console.log('Feature Flags server running on http://localhost:3000');
});

Как попробовать:

1. Запустите сервис (ts-node или компилятор TypeScript + node).
2. Откройте GET http://localhost:3000/checkout — по умолчанию будет старый чекаут.
3. Установите заголовки x-user-id, x-user-email, x-user-plan=pro — часть PRO‑пользователей увидит новый чекаут согласно проценту в правиле.
4. Меняйте флаг через PUT /flags/checkout.new, чтобы пробовать разные варианты правил и проценты.

Производственный уровень потребует: хранить флаги в базе, вести аудит, раздавать обновления через Pub/Sub, а SDK — кэшировать с TTL и экспозициями.

Фронт и мобильные клиенты: синхронизация и кэширование

• Где оценивать флаги. Для UI‑вариантов часто удобна клиентская оценка (мгновенно), для критичных серверных решений — на бэкенде.
• Доставка. Отдавайте JSON со всем набором флагов. Используйте ETag/If‑None‑Match для экономии трафика и быстрой проверки изменений.
• Кэш. Кэшируйте на 30–60 секунд. При ошибке сети используйте последнюю известную версию.
• Конфиденциальность. Не отправляйте в клиент условия, раскрывающие бизнес‑логику, если это чувствительно. В таких случаях оценка — только на сервере.

Минимальный протокол: GET /flags отдаёт JSON и ETag. Клиенты запрашивают периодически, получая 304 Not Modified, и обновляют локальный кэш только при изменениях.

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

• Роли и права. Управление флагами — только для доверенных ролей. Разделите права: кто создаёт, кто меняет, кто может «рубить» глобальный выключатель.
• Аудит. Логируйте: кто, когда, какой флаг, что изменил. Храните хотя бы 90 дней.
• Защита от ошибок. Двухэтапное подтверждение для массовых включений (на 100%). Шаблоны «стандартных» раскаток с контрольными точками.
• Валидация. Проверяйте, что проценты в сумме не больше 100, условия корректные, ключ уникален, срок жизни задан.

Жизненный цикл флага и «долг»

Флаги собирают «долг», если их не убирать. Чёткий цикл решает проблему:

1. Заведение: ключ, цель, владелец, срок жизни (дата удаления), тип флага.
2. Эксплуатация: раскатка по плану, мониторинг метрик, аудит изменений.
3. Завершение: заморозка значения, удаление условия из кода, удаление флага из хранилища.

Автоматизация помогает: линтер, который ругается на «просроченные» флаги; отчёты о флагах, не меняющих значение более N дней; кодмоды для массового удаления.

Метрики успеха и расчёт выгоды

• Скорость поставки: доля фич, выкатанных поэтапно; среднее время от «готово» до 100% включения.
• Надёжность: число откатов релизов; среднее время отключения проблемной фичи (цель — минуты, а не часы).
• Бизнес: изменение конверсии в целевых шагах после безопасной раскатки/экспериментов.

Простой расчёт: если команда тратит 10 часов в месяц на откаты/инциденты в релизах, а флаги режут это хотя бы наполовину, экономится ~5 часов × ставка × 12 месяцев — обычно это больше, чем стоимость внедрения.

План внедрения за 4 недели

• Неделя 1: Скелет. Сервис флагов, JSON‑формат, локальный кэш, ETag, аудит изменений. Один флаг на не‑критичную часть интерфейса.
• Неделя 2: SDK для бэкенда. Локальная оценка, фолбэк по умолчанию, метрики экспозиций. Первый «рубильник» для интеграции.
• Неделя 3: Поэтапные выкаты. Процентная раскатка по userId, шаблон плана (1%→5%→25%→100%), дашборд наблюдения.
• Неделя 4: Фронт/мобилки, роли и права, чек‑лист на PR, процесс удаления флагов. Пилотный A/B‑эксперимент.

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

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

Чек‑лист для команды

• Есть глобальный рубильник на критичные фичи?
• Оценка флагов происходит локально и работает при отказе сети?
• Процентная раскатка основана на стабильном идентификаторе?
• Есть аудит и роли доступа?
• У каждого флага есть владелец и срок жизни?
• Метрики экспозиций и влияния на бизнес подключены?

Итоги

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