Migração interna de contrato entre módulos sem big bang

O problema

Contrato interno muda por motivos normais:

• novo campo obrigatório
• semântica de comando mais clara
• resposta de leitura mais enxuta
• evento dividido em dois formatos mais específicos

O problema começa quando a solução proposta é:

“vamos trocar todo mundo ao mesmo tempo”

Em sistema real, isso quase nunca é tão limpo.

Sempre existe:

• consumidor esquecido
• worker atrasado
• script interno fora do fluxo principal
• módulo que depende da forma antiga

Modelo mental

Migrar contrato interno sem big bang normalmente significa passar por três fases:

• introduzir o novo contrato
• conviver por um período curto e observável
• remover o antigo com critério

O segredo não é conviver para sempre.

É conviver o suficiente para desligar sem loteria.

Exemplo simples

Imagine que o módulo de cobrança hoje recebe:

• CreateCharge(userId, amount, currency, metadata?)

Você quer migrar para:

• CreateCharge(accountId, money, reasonCode)

porque o modelo antigo virou ambíguo.

Se você só trocar a assinatura e for atualizando consumidores na sorte, o sistema quebra por ordem de deploy.

Uma migração mais saudável pode fazer:

• introdução do contrato novo
• adaptação temporária para o contrato antigo em pontos controlados
• medição de uso da forma velha
• remoção explícita quando ninguém mais depende

O erro comum

O erro comum é chamar qualquer convivência temporária de “bagunça”.

Às vezes ela é exatamente o que evita bagunça maior.

Outro erro comum é deixar a camada de compatibilidade virar definitiva.

Aí a migração nunca termina.

Então o problema não é só criar ponte.

É criar ponte com prazo e visibilidade.

O que normalmente ajuda

Migração interna melhor costuma incluir:

• contrato novo com nome ou forma claramente distinta
• adaptação local em pontos específicos, não espalhada pelo sistema
• sinal observável de uso do contrato velho
• critério claro de remoção

Em muitos casos, também ajuda:

• versionar evento internamente por um tempo
• publicar os dois formatos de maneira controlada
• manter tradução em um único módulo

O importante é não fazer cada consumidor resolver a ambiguidade sozinho.

Como um senior pensa

Quem tem mais julgamento costuma perguntar:

• quantos consumidores reais eu preciso migrar?
• consigo medir quem ainda depende do contrato antigo?
• a compatibilidade temporária está concentrada ou vazando para todo lado?
• qual é meu gatilho de remoção?

Essa conversa deixa a migração menos heroica e mais executável.

Ângulo de entrevista

Esse tema aparece em backend, modularização, eventos e evolução de sistemas.

O entrevistador quer ver se você entende:

• que contrato interno também precisa de compatibilidade retroativa temporária
• que migração segura quase nunca é simultânea
• que camada de adaptação tem que ser controlada e descartável

Resposta forte costuma soar assim:

“Eu evitaria virar todos os módulos de uma vez. Introduziria o contrato novo, concentraria a adaptação temporária em pontos específicos e mediria o uso do formato antigo. O objetivo é convivência curta com remoção explícita, não manter dois contratos para sempre.”

Takeaway direto

Migrar contrato interno sem big bang não é aceitar bagunça.

É trocar coordenação perfeita por transição controlada.