Шпаргалка · Поставка
Фича-флаги
Проблема
Магазин выкатывает новый checkout. Когда деплой и релиз — одно действие, баг достаётся всем пользователям, а путь назад — 15-минутный передеплой. Фича-флаги разделяют их: код уезжает выключенным, кто его видит, решает сервис флагов, SDK вычисляет флаги локально и получает изменения по стриму, kill switch гасит фичу за две секунды, а владелец и срок у каждого флага не дают старым флагам копиться.
Чему вы научитесь
- Почему деплой — не релиз и как выглядит правило флага с сегментом и процентом
- Локальное вычисление по кэшированному снапшоту и стрим обновлений вместо сетевого вызова на запрос
- Процентная раскатка по стабильному хэшу user id, kill switch и guardrail, который откатывает сам
- Устаревшие флаги как долг: владелец, срок и проверка в CI, которая валит сборку
Диаграмма как код
Итоговая схема урока в виде текста: вставьте её в Jira, GitLab, GitHub, Notion или документацию, там Mermaid рисуется сам. Есть варианты для D2 и PlantUML (Confluence, IntelliJ).
Mermaid: схема
flowchart LR
n_users(["Покупатели"])
n_api["Checkout API"]
n_db[("БД заказов")]
n_ci("CI/CD")
n_flags["Сервис флагов"]
n_team(("Команда checkout"))
n_users --> n_api
n_api --> n_db
n_ci --> n_api
n_team --> n_flags
n_api --> n_flags
n_flags -->|"асинхронно"| n_api
n_ci --x n_flagsMermaid: последовательность запросов
sequenceDiagram
participant n_ci as CI/CD
participant n_api as Checkout API
participant n_users as Покупатели
actor n_team as Команда checkout
participant n_flags as Сервис флагов
participant n_guard as Guardrail
Note over n_ci,n_api: Деплой и релиз — один и тот же момент
n_ci->>n_api: 14:00:00 deploy checkout v412 -#62; 24/24 pods
Note over n_users,n_api: Баг в новом флоу бьёт по всем
n_users->>n_api: POST /v1/checkout HTTP/1.1
n_api-->>n_users: HTTP/1.1 500 Internal Server Error
Note over n_team,n_flags: Код уезжает выключенным, решает флаг
n_team->>n_flags: PUT /v1/flags/new-checkout HTTP/1.1
n_flags-->>n_team: HTTP/1.1 200 OK
Note over n_api,n_flags: Сетевой вызов на каждый запрос: медленно и хрупко
n_api->>n_flags: 14:20:01 eval new-checkout user=u_42 remote 46 ms
Note over n_api,n_flags: SDK держит локальную копию и вычисляет в памяти
n_api->>n_flags: GET /v1/sdk/snapshot HTTP/1.1
n_flags-->>n_api: HTTP/1.1 200 OK
Note over n_flags,n_api: Изменения приходят по стриму
n_flags->>n_api: GET /v1/sdk/stream HTTP/1.1
n_api-->>n_flags: HTTP/1.1 200 OK
Note over n_users,n_api: Процентная раскатка по стабильному хэшу
n_users->>n_api: eval flag=new-checkout user=u_42 bucket=1873
Note over n_team,n_flags: Инцидент: не откат, а kill switch
n_team->>n_flags: PATCH /v1/flags/new-checkout HTTP/1.1
n_flags-->>n_team: HTTP/1.1 200 OK
Note over n_guard,n_flags: Guardrail выключает флаг сам
n_guard->>n_flags: GUARDRAIL new-checkout rollout 50% window 10 min
Note over n_ci,n_flags: Старые флаги копятся в долг
n_ci->>n_flags: flag-audit 2026-11-18: 142 flags, 61 stale
Note over n_ci,n_flags: У каждого флага есть владелец и срок
n_ci->>n_flags: ci flag-lint checkout@v431D2
direction: right
n_users: "Покупатели" {
shape: rectangle
}
n_api: "Checkout API" {
shape: rectangle
}
n_db: "БД заказов" {
shape: cylinder
}
n_ci: "CI/CD" {
shape: rectangle
style.multiple: true
}
n_flags: "Сервис флагов" {
shape: rectangle
}
n_team: "Команда checkout" {
shape: person
}
n_users -> n_api
n_api -> n_db
n_ci -> n_api
n_team -> n_flags
n_api -> n_flags
n_flags -> n_api: "асинхронно"
n_ci -> n_flags {
target-arrowhead.shape: cross
}PlantUML: последовательность запросов
@startuml
participant "CI/CD" as n_ci
participant "Checkout API" as n_api
participant "Покупатели" as n_users
actor "Команда checkout" as n_team
participant "Сервис флагов" as n_flags
participant "Guardrail" as n_guard
note over n_ci, n_api : Деплой и релиз — один и тот же момент
n_ci -> n_api : 14:00:00 deploy checkout v412 -> 24/24 pods
note over n_users, n_api : Баг в новом флоу бьёт по всем
n_users -> n_api : POST /v1/checkout HTTP/1.1
n_api --> n_users : HTTP/1.1 500 Internal Server Error
note over n_team, n_flags : Код уезжает выключенным, решает флаг
n_team -> n_flags : PUT /v1/flags/new-checkout HTTP/1.1
n_flags --> n_team : HTTP/1.1 200 OK
note over n_api, n_flags : Сетевой вызов на каждый запрос: медленно и хрупко
n_api -> n_flags : 14:20:01 eval new-checkout user=u_42 remote 46 ms
note over n_api, n_flags : SDK держит локальную копию и вычисляет в памяти
n_api -> n_flags : GET /v1/sdk/snapshot HTTP/1.1
n_flags --> n_api : HTTP/1.1 200 OK
note over n_flags, n_api : Изменения приходят по стриму
n_flags ->> n_api : GET /v1/sdk/stream HTTP/1.1
n_api -->> n_flags : HTTP/1.1 200 OK
note over n_users, n_api : Процентная раскатка по стабильному хэшу
n_users -> n_api : eval flag=new-checkout user=u_42 bucket=1873
note over n_team, n_flags : Инцидент: не откат, а kill switch
n_team -> n_flags : [повтор] PATCH /v1/flags/new-checkout HTTP/1.1
n_flags --> n_team : HTTP/1.1 200 OK
note over n_guard, n_flags : Guardrail выключает флаг сам
n_guard -> n_flags : GUARDRAIL new-checkout rollout 50% window 10 min
note over n_ci, n_flags : Старые флаги копятся в долг
n_ci -> n_flags : flag-audit 2026-11-18: 142 flags, 61 stale
note over n_ci, n_flags : У каждого флага есть владелец и срок
n_ci -> n_flags : ci flag-lint checkout@v431
@endumlPlantUML: компоненты
@startuml
left to right direction
agent "Покупатели" as n_users
component "Checkout API" as n_api
database "БД заказов" as n_db
collections "CI/CD" as n_ci
component "Сервис флагов" as n_flags
actor "Команда checkout" as n_team
n_users --> n_api
n_api --> n_db
n_ci --> n_api
n_team --> n_flags
n_api --> n_flags
n_flags --> n_api : асинхронно
n_ci -[#c62828]-> n_flags
@endumlИтог
Шесть правил для фича-флагов.
1) Деплой — не релиз: выкатывайте код выключенным, а кто его видит, решайте флагом. 2) Вычисляйте в памяти по снапшоту SDK; никакого сетевого вызова на запрос, и работайте дальше, если сервис флагов лежит. 3) Пушьте изменения стримом, чтобы выключение занимало секунды. 4) Раскатывайте по стабильному хэшу user id: пользователи не прыгают, а процент только добавляет людей. 5) Держите проверенный kill switch и guardrail, которые сами откатывают по метрикам. 6) У каждого флага есть владелец и срок, и CI это проверяет.
Показатели: в начале и в конце
| Показатель | В начале | В конце |
|---|---|---|
| Ошибки checkout | 0,4% | 0,4% |
| Время выключения | 900 с | 2 с |
| Checkout p99 | 180 мс | 181 мс |
| Устаревшие флаги | 0 | 4 |
Шаги
- Кейс Деплой и релиз — один и тот же момент
Команда доделывает новый checkout и мёржит PR.
- Проблема Баг в новом флоу бьёт по всем
Новый флоу иначе округляет налог, и часть корзин падает с
500. - Решение Код уезжает выключенным, решает флаг
Новый флоу теперь за
if (flags.on("new-checkout", user)). - Проблема Сетевой вызов на каждый запрос: медленно и хрупко
Каждый checkout теперь ждёт вызова сервиса флагов: 46–51 мс, и p99 растёт со 180 до 226 мс.
- Решение SDK держит локальную копию и вычисляет в памяти
API теперь использует SDK флагов.
- Решение Изменения приходят по стриму
SDK держит одно долгоживущее соединение с сервисом флагов по SSE (server-sent events).
- Решение Процентная раскатка по стабильному хэшу
Раскатка растёт с 5% до 25%.
- Решение Инцидент: не откат, а kill switch
На 25% в новом флоу растут отказы по картам: ошибки checkout у этих пользователей доходят до 4.8%.
- Решение Guardrail выключает флаг сам
Каждый checkout шлёт событие с полученным значением флага.
- Проблема Старые флаги копятся в долг
Через год флагов 142, и 61 из них устарел.
- Решение У каждого флага есть владелец и срок
Теперь флаг нельзя создать без владельца и срока.
- Итоги Итог
Шесть правил для фича-флагов.
Термины
- Kill switch
- Флаг, который выключает фичу для всех за секунды, без деплоя.
- Процентная раскатка
- Фича включается для доли пользователей по стабильному хэшу user id, и каждый всегда получает один и тот же ответ.
- Guardrail-метрика
- Метрика, по которой во время раскатки сравнивают группы с флагом и без, и при превышении лимита флаг выключается автоматически.