Feature flags

Escopo: transversal. Aplica-se a qualquer linguagem ou stack do projeto.

Feature flags (interruptores de funcionalidade) separam o ciclo de vida do código do ciclo de vida da feature. Código pode estar em produção desativado. Feature pode ser ativada para 1% dos usuários antes de 100%. Uma feature problemática pode ser desligada sem rollback de deploy.

Esta página aprofunda o vocabulário que ci-cd.md esboça na seção de deploy vs release. Flags como caso particular de configuração dinâmica aparecem também em configuration.md.

Nem toda flag serve ao mesmo fim. Misturar propósitos no mesmo mecanismo cria confusão: a regra de negócio convive com o experimento, o kill switch (desligador de emergência) convive com permissão de usuário. Quatro categorias cobrem a maioria dos casos:

Os quatro tipos têm auditoria, governança e prazo de validade diferentes. Release deve morrer. Permission nunca morre. Tratar todos como o mesmo tipo atrapalha a decisão de limpeza.

Uma flag não precisa ser binária ativa/inativa. Rollout controla quem vê a feature, em que proporção, em que ordem:

off              →  ninguém vê
internal         →  apenas contas do time e QA
beta             →  segmento opt-in (adesão voluntária) de clientes
% gradual        →  1% → 10% → 50% → 100%
segmentado       →  por plano, geografia, role, feature entitlement
on               →  todos veem

O padrão comum é: interno → beta → gradual → total. Cada transição é uma chance de observar métricas (erro, latência, conversão) antes de ampliar. Pular etapas é trocar visibilidade por velocidade.

Sinal de rollout mal feito: o time pula de 0% direto para 100%. A flag existe mas não entrega o benefício de release controlada. Vira apenas uma ramificação condicional extra no código.

Dark launch é colocar o código novo em produção sem que o usuário perceba. A feature roda em paralelo com a antiga: a lógica é executada, mas o resultado não é exposto. O output pode ser logado, comparado com o antigo ou descartado.

Três formas típicas:

Dark launch é a forma mais segura de validar um caminho crítico (migração de banco, reescrita de cálculo, troca de provedor). Mais caro de implementar, mais barato que um incidente em produção.

Kill switch é a flag que desliga uma feature problemática em segundos, sem abrir PR (Pull Request, Pedido de Integração), sem rebuild (recompilação), sem deploy. É a rede de segurança quando algo descompensa: picos de erro, latência fora do limite, regressão detectada em métrica.

Diferente de uma flag de release, o kill switch:

O desenho é: para toda feature nova de alto risco (escrita, cobrança, integração externa), existe kill switch desde o primeiro deploy. Descobrir na meia-noite do incidente que não há switch é descobrir tarde demais.

Uma flag é avaliada em três pontos possíveis, cada um com trade-off (equilíbrio entre fatores) próprio:

A maioria das flags úteis é runtime: o valor muda sem restart (reinicialização), o rollout é ajustável, o kill switch responde ao incidente imediatamente.

O custo por avaliação importa. Consultar um serviço externo a cada chamada de função é insustentável. O padrão é cache local com TTL (Time To Live, tempo de validade) curto: o cliente da flag sincroniza com o backend a cada poucos segundos e responde localmente ao código. Ver performance.md seção Cache.

Como a flag aparece no código determina se ela será fácil de remover depois. Três padrões:

1. inline (embutido no fluxo) espalhado (pior)

Vira código duplicado e quase impossível de remover.

if (flags.isNewCheckoutEnabled) {
  ... 80 linhas do novo fluxo ...
} else {
  ... 80 linhas do antigo ...
}

2. isolamento por função (aceitável)

Cobre a maior parte dos casos: a flag escolhe qual implementação injetar, as duas implementações são pares independentes.

const checkout = flags.isNewCheckoutEnabled ? newCheckout : legacyCheckout;
checkout.process(order);

3. strategy (estratégia) com registro (escalável)

Vale quando há mais de duas variantes ou a decisão de qual variante usar depende de vários fatores.

const strategy = checkoutStrategies[flags.checkoutVariant];
strategy.process(order);

A regra é: a flag define qual caminho segue; o caminho não sabe que foi escolhido por flag. O consumidor chama checkout.process(order) sem if em volta. Remover a flag, depois que a nova implementação venceu, é apagar a escolha e manter a implementação.

Flag que nunca é removida vira débito permanente: condicional no código, configuração no sistema, cognição para quem lê. O custo cresce em juros compostos: quantas flags inativas estão rodando hoje? Quais são seguras de remover?

Três práticas contêm a dívida:

Sinal de má gestão: o time tem dezenas de flags ligadas em 100% há meses. O sistema de flags virou registro arqueológico de decisões antigas, não ferramenta de release.

O código com flag tem pelo menos dois caminhos. Os dois precisam ser testados. Dois padrões funcionam:

O que não funciona: ler o flag service real em teste. O teste passa a depender de configuração externa e vira frágil.

Desenvolvido por @thiagocajadev · Fork baseado no repositório pmndrs/docs · Poimandres.