Migração código legado: guia prático para arquitetura moderna

Se você trabalha com desenvolvimento há alguns anos, já deve ter encarado um sistema legado: aquele monolito que roda num servidor antigo, com código que ninguém quer tocar. Migrar para uma arquitetura moderna não é um projeto de fim de semana, é uma cirurgia de risco médio que, quando bem planejada, evita paradas, retrabalho e desperdício de dinheiro. Neste guia, mostro como migrar código legado para arquitetura moderna em passos concretos, com base no que funciona no uso real, e não no discurso de palestra.

Antes de começar, você precisa de três coisas: um inventário do sistema (quais módulos, dependências, integrações), um ambiente de testes que reproduza o comportamento do legado, e o aval da área de negócios para eventuais pausas. Sem isso, qualquer plano vira achismo.

Passo 1: Mapear o sistema legado sem confiar na documentação

O primeiro erro é achar que a documentação do sistema reflete a realidade. Pegue o código fonte, o banco de dados e os logs em produção. Liste cada funcionalidade, cada integração com APIs externas, cada job agendado. Anote também o que ninguém usa mais, funcionalidades mortas que só aumentam a dívida técnica.

Dica prática: use ferramentas de análise estática (como SonarQube ou Understand) para gerar um grafo de dependências. Isso revela acoplamentos que você não enxerga no dia a dia. Um erro comum é pular essa etapa e descobrir, no meio da migração, que um módulo aparentemente isolado depende de uma biblioteca que não existe mais.

Passo 2: Escolher a estratégia de migração (big bang ou incremental)

Aqui vai a decisão que define o custo e o risco do projeto. A abordagem big bang, migrar tudo de uma vez e trocar a chave, funciona apenas para sistemas muito pequenos (até 20 mil linhas de código, com baixo acoplamento). Para qualquer coisa maior, o incremental é mais seguro.

No incremental, você isola um módulo por vez, cria uma camada de adaptação (strangler fig pattern) e redireciona o tráfego gradualmente. O erro comum: tentar fazer incremental sem uma estratégia de rollback clara. Se o módulo novo falhar, você precisa voltar ao legado em minutos, não em dias.

Passo 3: Priorizar módulos por risco e valor de negócio

Nem todo módulo merece ser migrado primeiro. Crie uma matriz simples: eixo X = valor de negócio (quanto impacto financeiro ou operacional a funcionalidade gera), eixo Y = risco técnico (acoplamento, falta de testes, idade do código). Comece pelos módulos de alto valor e baixo risco, eles geram resultado rápido e validam o processo.

Evite começar pelo módulo mais crítico (como processamento de pagamentos) se ele tiver alto risco. Um erro aí pode parar o negócio. Prefiro começar por uma tela de consulta ou relatório, que dá para testar com calma.

Passo 4: Refatorar ou reescrever? A pergunta que ninguém responde bem

Refatoração mantém a lógica de negócio e troca apenas a infraestrutura (linguagem, framework, banco). Reescrita recria o módulo do zero. A regra que uso: se o código legado tem cobertura de testes acima de 60% e a lógica de negócio é estável, refatore. Se o código é uma sopa de if-else sem testes e a regra mudou, reescreva.

Um contraexemplo real: certa vez, uma equipe reescreveu um módulo de cálculo de impostos porque o código era feio. Descobriram, depois de dois meses, que o legado tratava exceções fiscais que a nova versão ignorou. O custo de reescrever o que não se entende completamente é alto. Por isso, sempre documento o comportamento observado antes de tocar no código.

Passo 5: Criar uma camada de testes de regressão automatizada

Sem testes, migração é aposta. Monte um conjunto de testes de regressão que cubra pelo menos os fluxos principais do módulo que será migrado. Ferramentas como Selenium para front-end ou Postman para APIs ajudam a capturar o comportamento atual.

Dica: grave o tráfego de produção por uma semana e replique as requisições no ambiente de teste. Isso garante que você testa com dados reais, não com cenários inventados. O erro comum é criar testes que passam no legado e no novo sistema porque são genéricos demais, use asserções específicas para valores de saída.

Passo 6: Executar a migração em ciclos curtos com validação de negócio

Cada módulo migrado deve ser validado por quem usa o sistema no dia a dia, não pelo time de TI. Defina ciclos de duas semanas: uma semana para migrar, uma semana para testar com o usuário. Se o módulo falhar na validação, volte ao legado e ajuste.

Um erro que vejo com frequência é o time querer migrar vários módulos em paralelo para "ganhar tempo". Na prática, isso multiplica os pontos de falha e dificulta o rollback. Prefiro um módulo por vez, mesmo que o cronograma pareça longo. O custo de corrigir um erro em produção é sempre maior que o de esticar o prazo.

Passo 7: Descomissionar o legado com cuidado

Quando todos os módulos estiverem rodando na nova arquitetura, não desligue o sistema antigo imediatamente. Mantenha-o em modo somente leitura por pelo menos 30 dias, com logs de erro monitorados. Isso permite detectar funcionalidades esquecidas que ainda são acessadas por integrações ocultas.

O checklist final: inventário completo, estratégia definida, módulos priorizados, testes de regressão rodando, migração incremental concluída, legado em modo de espera. Se você seguiu esses passos, o risco de uma surpresa desagradável cai drasticamente.

FAQ: Perguntas frequentes sobre migração de código legado

Qual a diferença entre refatoração e reescrita?

Refatoração altera a estrutura interna do código sem mudar o comportamento externo; reescrita cria um novo sistema do zero. Refatorar é mais seguro quando o código tem testes e a lógica é estável. Reescrever faz sentido quando o legado está tão degradado que refatorar custaria mais que recomeçar.

Quanto tempo leva uma migração de código legado?

Depende do tamanho do sistema e da estratégia. Para um monolito de 100 mil linhas com baixo acoplamento, uma migração incremental pode levar de 3 a 6 meses. Sistemas maiores ou com muitas integrações podem levar mais de um ano. O erro é prometer prazos curtos sem mapear o legado antes.

Devo usar microsserviços na migração?

Nem sempre. Se o sistema legado tem domínio bem delimitado e não precisa escalar partes independentes, um monolito modular bem refatorado pode ser suficiente. Microsserviços adicionam complexidade de rede, monitoramento e deploy. Avalie se o ganho real justifica o custo operacional.

Como evitar que a migração pare o negócio?

Usando a abordagem incremental com padrão strangler fig: cada módulo novo substitui o antigo sem interromper o fluxo. Mantenha rollback automático e comunique os usuários sobre janelas de manutenção. O risco zero não existe, mas com testes e validação por módulo, o impacto é controlado.

Preciso de ferramentas específicas para migrar?

Ferramentas de análise estática (SonarQube), orquestração de containers (Docker, Kubernetes) e monitoramento (Prometheus, Grafana) ajudam, mas não são obrigatórias no início. O essencial é um ambiente de testes que reproduza produção e um repositório de código com versionamento. O resto você adiciona conforme a necessidade.

Qual o maior erro em migrações de código legado?

Subestimar o esforço de entender o comportamento real do sistema. Muitas equipes começam a reescrever sem documentar o que o legado faz, e descobrem funcionalidades críticas só depois de quebrar algo em produção. O tempo gasto mapeando o sistema nunca é desperdiçado.