Feature flags: como liberar funcionalidades com mais segurança

O que são feature flags?

Feature flags, também chamadas de feature toggles, são controles que alteram o comportamento de uma aplicação sem exigir uma nova modificação no código-fonte.

A definição adotada pelo projeto OpenFeature destaca justamente essa capacidade de ativar, desativar ou mudar um recurso em tempo de execução.

Uma flag pode responder a uma pergunta booleana, como “usar o novo checkout?”, ou retornar uma variante, uma configuração numérica ou um objeto.

A decisão pode valer para todos, para uma porcentagem do público ou para um contexto específico, como plano contratado, região, organização ou versão do aplicativo.

O benefício não está na condicional isolada. Ele surge quando a equipe combina o controle com critérios claros de ativação, telemetria, testes, responsável definido e prazo de remoção.

Deploy e lançamento são etapas diferentes

Deploy é o ato de colocar uma versão em um ambiente. Lançamento é a decisão de expor uma capacidade ao público.

Sem flags, essas etapas costumam ficar acopladas: assim que o deploy termina, o usuário encontra o novo comportamento.

Com uma flag, o código novo pode acompanhar a mesma esteira descrita no guia de CI/CD para iniciantes, passar por produção sem ficar visível e ser liberado por uma decisão operacional posterior.

Isso diminui a pressão sobre a janela de publicação e permite interromper a exposição sem reconstruir todo o artefato.

Essa técnica não substitui revisão, testes automatizados, deploy confiável ou rollback de versão. Ela adiciona uma camada de controle ao processo.

Como uma feature flag é avaliada

Em uma avaliação típica, a aplicação informa a chave da flag, um valor padrão e, quando necessário, um contexto.

O mecanismo consulta regras locais ou um provedor e devolve a variante correspondente.

• Chave: nome estável e legível, como novo-checkout.
• Valor padrão: comportamento seguro quando a avaliação falha.
• Contexto: atributos necessários para segmentação, sem coletar dados por precaução.
• Regra: condições, porcentagens e prioridades que determinam o resultado.
• Variante: valor final usado pela aplicação.

Na prática, o SDK deve evitar uma chamada remota síncrona em cada requisição.

Cache, atualização em segundo plano e um último valor conhecido ajudam a preservar a disponibilidade do serviço principal.

Principais tipos de feature flags

A classificação popularizada por Martin Fowler ajuda a definir a duração e o tratamento esperado de cada controle:

• Flags de lançamento: escondem um recurso incompleto ou permitem a adoção progressiva. Costumam ser temporárias.
• Flags de experimento: distribuem variantes para comparar resultados. Precisam de hipótese, métrica e encerramento.
• Flags operacionais: funcionam como um disjuntor para reduzir carga ou desligar uma integração instável. Podem durar mais, desde que sejam exercitadas.
• Flags de permissão: diferenciam capacidades por plano, cliente ou programa de acesso. Não devem substituir autorização de segurança.

Definir o tipo antes da implementação evita tratar da mesma forma um experimento de duas semanas e um controle operacional permanente.

Exemplo prático com Node.js e TypeScript

O exemplo abaixo usa a API do OpenFeature. Um provider compatível precisa ser configurado na inicialização da aplicação.

O valor false é o fallback: se não houver resposta válida, o checkout atual continua em uso.

import { OpenFeature } from '@openfeature/server-sdk';

const client = OpenFeature.getClient();

export async function finalizarCompra(usuario: Usuario, pedido: Pedido) {
  const usarNovoCheckout = await client.getBooleanValue(
    'novo-checkout',
    false,
    {
      targetingKey: usuario.id,
      plano: usuario.plano
    }
  );

  return usarNovoCheckout
    ? novoCheckout(usuario, pedido)
    : checkoutAtual(usuario, pedido);
}

O targetingKey oferece uma identidade estável para manter o mesmo usuário no mesmo grupo.

O atributo de plano só deve ser enviado se realmente participar da regra.

Centralize as decisões de produto

Espalhar verificações da mesma flag por controladores, componentes e filas dificulta a remoção.

Uma alternativa é traduzir flags técnicas para decisões do domínio em um único módulo.

type DecisoesDeCompra = {
  usarNovoCheckout: boolean;
};

function escolherFluxo(decisoes: DecisoesDeCompra) {
  return decisoes.usarNovoCheckout ? novoCheckout : checkoutAtual;
}

Assim, a regra de segmentação permanece na borda e o núcleo recebe uma decisão simples.

Essa separação também facilita testes unitários e combina com as boas práticas para criar APIs.

Rollout gradual sem usuários alternando de grupo

Um rollout gradual começa com um grupo pequeno e aumenta à medida que métricas técnicas e de negócio permanecem saudáveis.

Antes do público externo, a equipe pode liberar o recurso para desenvolvimento, homologação e usuários internos.

A distribuição percentual precisa ser determinística. O sistema combina uma chave estável — como o identificador do usuário ou da organização — com a chave da flag para posicionar aquela entidade em um intervalo.

Se a escolha fosse aleatória a cada requisição, a mesma pessoa poderia alternar entre fluxos e produzir dados inconsistentes.

A documentação de feature flags do GitLab chama essa estabilidade de stickiness e apresenta estratégias por porcentagem, identificadores e listas.

Escolha a entidade correta: em um sistema B2B, distribuir por organização costuma ser mais coerente do que separar membros da mesma empresa.

Avaliação no servidor ou no cliente?

No servidor, regras e credenciais ficam fora do alcance do navegador. Essa abordagem é adequada para lógica sensível, integrações, preços e recursos privilegiados.

No cliente, a avaliação pode facilitar mudanças visuais rápidas e reduzir latência, mas a configuração deve ser considerada pública e manipulável.

Nunca coloque segredos em uma flag enviada ao navegador. Também não use a flag como única barreira de acesso.

Um botão pode ficar oculto, mas a API ainda precisa validar autenticação e autorização, seguindo os princípios de segurança no código desde o início.

Fallbacks e indisponibilidade do provedor

O serviço de flags é uma dependência operacional. A aplicação deve continuar funcionando quando ele estiver lento, indisponível ou entregar uma regra inválida.

• Defina um valor padrão seguro para cada avaliação.
• Use cache local e, quando fizer sentido, o último estado válido.
• Estabeleça tempo limite curto para inicialização e atualização.
• Monitore erros de avaliação e idade da configuração armazenada.
• Documente o comportamento esperado durante a falha.

O fallback nem sempre é “desligado”. Para um controle operacional que protege um serviço sobrecarregado, o estado mais seguro pode ser manter uma funcionalidade não essencial desativada.

Como testar feature flags

Enquanto a flag existir, os dois caminhos são código de produção. Teste o estado padrão e a variante nova em unidades, integrações e cenários críticos de ponta a ponta.

Não é necessário executar toda combinação possível de dezenas de flags: isso cresce exponencialmente.

Priorize o estado padrão do ambiente, o próximo estado planejado, interações conhecidas e fluxos de alto risco.

Quando duas flags dependem uma da outra, registre a dependência ou substitua-as por uma decisão de nível mais alto.

Também vale ensaiar o kill switch. Um controle de emergência que nunca foi acionado pode falhar justamente quando a equipe precisa dele.

Observabilidade durante o rollout

Antes de ampliar a exposição, escolha indicadores de sucesso e proteção. Taxa de conversão pode medir resultado, enquanto erros, latência, saturação, cancelamentos ou chamadas ao suporte funcionam como limites de segurança.

Inclua a chave e a variante da flag em logs estruturados, métricas ou spans, sem registrar dados pessoais desnecessários.

Evite usar identificadores de usuários como rótulos de métricas, pois isso cria alta cardinalidade e aumenta custo. O artigo sobre OpenTelemetry mostra como correlacionar traces, métricas e logs durante uma investigação.

Compare grupos equivalentes e mantenha uma janela de observação compatível com o tráfego. Ausência de alerta nos primeiros minutos não prova que uma mudança está segura.

Feature flag não desfaz efeitos colaterais

Desativar uma flag seleciona outro caminho para as próximas execuções. Isso não reverte automaticamente uma migração de banco, um pagamento confirmado, um e-mail enviado, um evento publicado ou dados já transformados.

Planeje compatibilidade entre versões. Prefira mudanças de banco expansíveis e reversíveis: primeiro adicione estruturas compatíveis, depois migre leituras e escritas e só remova o formato antigo após a consolidação.

Em microsserviços, consumidores e produtores podem permanecer em versões diferentes por algum tempo, o que torna esse cuidado ainda mais importante.

Governança e remoção de flags antigas

Cada flag aumenta o número de estados que alguém precisa compreender. Uma flag temporária que permanece por anos deixa de ser uma ferramenta de entrega e vira complexidade acidental.

No momento da criação, registre proprietário, objetivo, tipo, data, estado padrão, ambientes, critério de sucesso, plano de reversão e data prevista para revisão.

O inventário deve indicar quais controles estão ativos e quais já podem ser removidos.

Quando a nova variante chegar a 100% e estiver estável, remova a ramificação antiga, a chamada de avaliação, os testes exclusivos do caminho descontinuado e a configuração no provedor.

Faça essa limpeza em uma alteração pequena e rastreável.

Solução própria, plataforma ou padrão aberto?

Uma configuração local pode atender a um sistema pequeno com poucas flags.

À medida que surgem múltiplos serviços, ambientes, auditoria, segmentação e aprovação de mudanças, uma plataforma dedicada reduz trabalho operacional.

Avalie disponibilidade, latência, SDKs, cache, trilha de auditoria, controle de acesso, exportação de dados e custo.

Também considere o risco de acoplamento. O OpenFeature oferece uma API independente de fornecedor e usa providers para conectar diferentes mecanismos, o que permite preservar a interface da aplicação durante uma troca.

Se a equipe opera a própria infraestrutura, trate configurações, credenciais e permissões com o mesmo rigor aplicado em infraestrutura como código.

Erros comuns ao usar feature flags

• Usar nomes vagos: nova-tela perde significado; prefira um nome ligado à capacidade.
• Avaliar aleatoriamente por requisição: usuários alternam de experiência e dados ficam incoerentes.
• Não definir fallback: uma falha do provedor passa a derrubar o produto.
• Tratar flag como autorização: ocultar interface não protege a operação no servidor.
• Liberar sem métricas: a equipe não sabe quando avançar ou interromper.
• Acumular flags antigas: testes, leitura e manutenção ficam mais difíceis.
• Combinar muitas flags: estados impossíveis de compreender surgem em produção.

Checklist para uma liberação segura

1. Defina objetivo, proprietário e duração esperada.
2. Escolha um valor padrão seguro e documente falhas.
3. Centralize a avaliação e evite condicionais espalhadas.
4. Teste os caminhos atual e novo.
5. Determine o público inicial e uma chave estável de distribuição.
6. Defina métricas de sucesso e limites de interrupção.
7. Valide logs, métricas, traces e alertas antes da exposição.
8. Amplie o público em etapas com tempo para observação.
9. Consolide a variante vencedora e remova a flag.

Perguntas frequentes

Feature flag é o mesmo que configuração?

Uma feature flag é um tipo de configuração voltada a decisões de comportamento e lançamento.

Nem toda configuração é uma flag: endereço de serviço, limite técnico e credencial, por exemplo, têm outros ciclos e controles.

Feature flags substituem rollback?

Não. Elas podem interromper a exposição de um comportamento, mas não desfazem efeitos já produzidos nem corrigem um artefato defeituoso fora do caminho controlado.

Quantas flags uma aplicação pode ter?

Não existe um limite universal. O sinal de alerta é a equipe não saber quem é responsável, quais combinações são válidas ou quando uma flag será removida.

Rollout percentual é o mesmo que teste A/B?

Não necessariamente. O rollout reduz risco operacional e pode ampliar uma única variante. O teste A/B exige hipótese, grupos comparáveis, métrica definida e análise estatística.

Feature flags funcionam em aplicativos móveis?

Sim. Elas ajudam porque a atualização instalada pelos usuários pode demorar. Ainda assim, o aplicativo precisa de fallback, cache e compatibilidade com configurações antigas.

Quem deve poder alterar uma flag?

Somente pessoas e serviços autorizados, conforme o impacto. Controles críticos pedem menor privilégio, auditoria e, em alguns casos, aprovação de outra pessoa.

Conclusão

Feature flags tornam a liberação de software mais controlável porque separam deploy de lançamento, permitem exposição gradual e oferecem um caminho rápido para reduzir o impacto de problemas.

O resultado depende de disciplina: coortes estáveis, fallback seguro, testes dos dois caminhos, observabilidade, autorização real no servidor e remoção após o uso.

Comece com uma flag temporária, defina antes como ela termina e trate sua exclusão como parte da entrega.