Feature flag implementacao: guia passo a passo em 5 etapas

Feature flag implementacao parece simples a primeira vista: um if no codigo e pronto. Mas a pratica mostra que o diabo mora nos detalhes. Se voce ja tentou criar uma flag e viu o deploy virar um pesadelo, este guia e para voce. Vou mostrar um caminho de 5 etapas que uso em projetos reais, com erros comuns que prefiro evitar.

A especificacao impressiona, o uso decide. Antes de comecar, o resultado esperado e ter flags que podem ser ligadas e desligadas sem deploy, com risco controlado. Pre-requisitos: conhecimento basico de git, um servico de configuracao remota ou um banco de dados, e um sistema de logs ja funcionando. Sem isso, voce vai improvisar, e improviso em flag e receita para incidente.

Passo 1: Defina a flag com nome e proposito claros

Toda flag comeca com uma decisao: o que ela controla? Pode ser uma nova tela de checkout, um algoritmo de recomendacao ou a troca de um provedor de pagamento. O nome precisa dizer exatamente isso. Em vez de novaFeature, use checkout_novo_layout_v2. Esse nome aparece em logs, em dashboards e em conversas de equipe. Nome generico gera confusao.

Defina tambem o tipo de flag. Existem flags de release (liga uma funcao nova), de experimento (testa variacoes) e de operacao (desliga um servico em crise). Cada tipo tem ciclo de vida diferente. Uma flag de release deve ser temporaria, removida apos o rollout completo. Uma de operacao pode viver por anos.

Erro comum: criar flag sem dono. Se ninguem e responsavel por ela, ninguem remove quando o recurso esta estavel. O codigo acumula if mortos que ninguem entende.

Passo 2: Adicione a logica condicional no codigo

Chegou a hora do if. A regra basica: a condicao deve ficar o mais proxima possivel do ponto de decisao, mas sem espalhar logica de negocio. Use uma funcao centralizada, tipo isFlagActive('checkout_novo_layout_v2'). Isso evita que cada desenvolvedor implemente a leitura da flag de um jeito diferente.

Um exemplo concreto: voce tem um servico de pagamento antigo e um novo. Em vez de colocar if em dez lugares, crie uma fabrica que retorna o provedor certo com base na flag. Assim, a troca acontece em um unico ponto. Se precisar desativar o novo provedor as 3 da manha, voce muda a configuracao, nao o codigo.

Erro comum: usar a flag para esconder codigo quebrado. Se a feature nova nao funciona sem a flag, ela nao deveria ir para producao nem desativada. A flag serve para controlar o risco de algo que esta pronto, nao para mascarar bug.

Passo 3: Armazene a configuracao fora do codigo

Flag hardcoded no codigo e sinonimo de deploy para mudar qualquer coisa. O ideal e ter a configuracao em um servico de feature management (como LaunchDarkly ou Split) ou, em cenarios mais simples, em um banco de dados com cache. Para times pequenos, um arquivo JSON versionado pode funcionar, desde que o deploy da flag nao dependa do deploy da aplicacao.

O criterio para escolher a ferramenta: o tempo entre mudar a configuracao e o efeito no sistema. Se leva mais de um minuto, voce perdeu o beneficio principal da flag. Em um projeto proprio, ja usei um arquivo local com reload por polling a cada 30 segundos. Funcionava, mas exigia reiniciar o servidor em alguns casos. Nao recomendo para producao.

Erro comum: colocar a configuracao junto com variaveis de ambiente. Variaveis de ambiente sao para configuracao estatica, que muda pouco. Flags mudam a cada release. Se voce mistura os dois, vai dar deploy para alternar uma flag, o que anula a proposta.

Passo 4: Valide a flag em ambiente controlado antes de liberar

Antes de ligar para todos, valide a flag em um ambiente de staging ou com um grupo pequeno de usuarios internos. O objetivo e responder: a feature nova funciona com dados reais? O codigo antigo continua acessivel se a flag estiver desligada?

Um teste simples: ligue a flag em staging, execute o fluxo principal e desligue. Verifique se o sistema volta ao comportamento anterior sem erros. Esse teste de reversao e mais importante que testar a feature em si. Se a reversao falhar, voce nao pode usar a flag com seguranca.

Depois do staging, faca um rollout gradual em producao. Em vez de 100% dos usuarios de uma vez, comecce com 5% ou 10%. Observe metricas de erro e latencia por alguns minutos. Se tudo estiver estavel, aumente para 50% e depois para 100%. Esse processo pode levar horas ou dias, dependendo do risco.

Erro comum: pular a validacao e ligar a flag direto para todos. Se algo der errado, voce nao sabe se o problema e da feature ou da flag em si. O gradualismo existe para dar visibilidade.

Passo 5: Monitore o impacto e remova a flag quando nao precisar mais

Flag ligada nao e fim de trabalho. E o comeco. Acompanhe logs de erro, tempo de resposta e taxa de conversao (se for uma feature de negocio). Se a flag controla um checkout, monitore a taxa de abandono. Se controla um algoritmo, monitore a precisao.

O ponto de remocao chega quando a feature esta estavel para todos os usuarios e nao ha plano de voltar. Nesse momento, remova o codigo da feature antiga e a condicional da flag. Deixe apenas a feature nova. Isso reduz complexidade e evita que flags antigas interfiram em mudancas futuras.

Um erro que ja cometi: manter uma flag de release por meses apos o rollout. Quando outro dev precisou mexer naquele trecho, gastou horas tentando entender por que existiam dois caminhos de codigo. A flag virou divida tecnica.

Checklist rapido do que foi feito

• [ ] Defini nome e tipo da flag, com dono responsavel
• [ ] Adicionei logica condicional centralizada, sem espalhar ifs
• [ ] Configurei armazenamento externo com efeito em menos de 1 minuto
• [ ] Validei em staging e fiz rollout gradual em producao
• [ ] Monitorei metricas de erro e negocio apos ligar
• [ ] Removi a flag e o codigo antigo apos estabilizacao

Se voce seguiu esses passos, tem flags que funcionam como ferramenta de controle, nao como fonte de bug. O proximo passo e criar um processo de revisao periodica: agende uma tarefa mensal para listar flags ativas e questionar se cada uma ainda e necessaria. Isso mantem o codigo limpo e o sistema previsivel.

FAQ

Qual a diferenca entre feature flag e feature toggle?

Nenhuma pratica. Feature flag e o termo mais comum no mercado, feature toggle e o nome usado por Martin Fowler em artigos classicos. Ambos descrevem a mesma tecnica: condicionais que controlam a disponibilidade de uma funcionalidade em tempo de execucao.

Feature flag implementacao funciona em qualquer linguagem?

Sim. A tecnica depende de condicionais e de um servico de configuracao, que existem em praticamente toda linguagem. O que muda e a biblioteca de apoio. Em Node.js, por exemplo, voce pode usar o pacote flag ou criar uma funcao propria. Em Python, um dicionario com valores booleanos resolve.

Preciso de uma ferramenta paga para fazer feature flag?

Nao. Para times pequenos, um banco de dados com cache ou um arquivo JSON versionado ja resolve. Ferramentas pagas oferecem conveniencia: painel visual, auditoria e segmentacao avancada. Mas o custo so se justifica quando voce tem muitas flags e varios times usando.

Como evitar que flags acumuladas virem divida tecnica?

Crie uma politica de ciclo de vida: toda flag de release tem data de expiracao de 30 a 60 dias apos o rollout. Inclua a remocao da flag como tarefa no planejamento da sprint seguinte ao release. Se a flag nao for removida no prazo, o tech lead deve cobrar.

Feature flag substitui branch de feature ou deploy por ambiente?

Nao substitui, complementa. Branch de feature isola codigo em desenvolvimento. Deploy por ambiente testa em staging. Feature flag permite integrar codigo ao branch principal com a feature desligada, reduzindo conflitos de merge. As tres tecnicas convivem.

Qual o risco de usar flag para desligar um servico em crise?

O risco e baixo se a flag de operacao for bem testada. O problema aparece quando a flag desliga um servico que outros sistemas dependem, causando efeito cascata. Antes de criar uma flag de operacao, mapeie as dependencias. Se possivel, use circuit breaker em vez de flag para questoes de infraestrutura.

Feature flag implementacao bem feita reduz o medo de deploy e da mais confianca para entregar com frequencia. A especificacao impressiona, o uso decide. Comece com uma flag simples, valide o processo e depois escale. O resto e pratica.