Depreciação de Contrato Sem Pegar Consumidor de Surpresa

O problema

Quando um time quer mudar contrato, a tentacao mais comum e esta:

1. marca como deprecated
2. avisa no Slack
3. espera o mundo se atualizar

Isso quase nunca basta.

Contrato velho não some porque você publicou uma mensagem.

Ele continua vivo em:

• cliente mobile atrasado
• integração externa
• job interno esquecido
• consumidor de evento de baixo volume

Depreciação ruim não falha porque faltou etiqueta.

Falha porque faltou estratégia.

Modelo mental

Pense assim:

depreciação de contrato e uma migração de ecossistema, não só uma mudança de interface

Isso significa que o problema não esta só no produtor.

Esta na relação entre:

• quem produz
• quem consome
• quem ainda não migrou
• quem nem sabe que depende daquilo

Depreciação boa e o processo de tirar esse suporte sem surpreender o ecossistema inteiro ao mesmo tempo.

Quebrando o problema

Descubra quem ainda usa o contrato antigo

Sem visibilidade de uso, a remoção vira chute.

Você precisa saber:

• quais consumidores ainda chamam a versão velha
• quais campos antigos ainda aparecem
• que volume e criticidade esse tráfego tem
• se ha parceiros externos fora do seu controle

Depreciação sem medição e corte no escuro.

Diferencie aviso de convivencia

Avisar ajuda.

Mas o que realmente protege e a fase de convivencia.

Nela, o sistema:

• continua aceitando o formato antigo por um tempo
• orienta migração para o novo
• mede adocao
• prepara remoção com data e critério claros

Sem essa etapa, o prazo de depreciação vira mais ameaca do que engenharia.

Deixe o contrato novo aditivo quando puder

Mudança mais segura costuma ser:

• campo novo opcional
• valor novo documentado
• endpoint novo convivendo com o antigo

Mudança mais agressiva costuma ser:

• remover campo exigido cedo
• trocar semântica silenciosamente
• responder com formato diferente sob a mesma promessa

Quanto mais aditiva for a transição, mais chance de o ecossistema atravessar sem drama.

Defina critério real para remoção

Data sozinha não basta.

Você também precisa definir:

• qual percentual de uso antigo ainda e aceitavel
• quais consumidores obrigatoriamente precisam migrar antes
• como tratar exceções temporarias
• como detectar regressao depois da remoção

Se isso não esta explícito, o dia da remoção vira disputa politica.

Não esconda breaking change atras de versão ou label

Colocar v2 ou deprecated no nome não resolve o problema por si só.

Se o contrato novo continua pegando consumidor de surpresa, a engenharia continua fraca.

Rotulo sem estratégia de convivencia e só maquiagem.

Exemplo simples

Imagine um endpoint que hoje responde:

{
  "status": "paid",
  "amount": 1000
}

O time quer passar a responder:

{
  "paymentStatus": "paid",
  "amountCents": 1000
}

Plano ruim:

• muda o payload
• avisa a equipe cliente
• considera assunto resolvido

Plano melhor:

1. introduz novos campos sem remover os antigos
2. documenta qual e o caminho futuro
3. mede quem ainda consome os campos antigos
4. acompanha migração dos consumidores principais
5. só remove quando o uso residual estiver entendido e controlado

Isso e mais chato.

Também e bem menos destrutivo.

Erros comuns

• Achar que comunicado substitui compatibilidade.
• Não medir uso do contrato antigo antes da remoção.
• Fazer breaking change silenciosa sob o mesmo endpoint.
• Definir data de corte sem olhar consumidores reais.
• Deixar depreciação eterna porque ninguém assumiu dono da remoção.

Como um senior pensa

Quem tem mais experiência trata depreciação como problema de coordenação técnica.

A pergunta boa costuma ser:

“Quem eu ainda quebro se remover isso amanha, e como eu descubro isso antes de descobrir em produção?”

Essa pergunta e muito mais útil do que só decidir um prazo bonito.

O que o entrevistador quer ver

Em entrevista, o avaliador quer ver se você sabe evoluir contrato sem jogar custo escondido no consumidor.

Você sobe de nivel quando:

• fala de medição de uso
• explica fase de convivencia
• prefere transição aditiva quando possível
• define critério de remoção, não só anuncio de depreciação

Uma resposta forte costuma soar assim:

“Eu não trataria depreciação como aviso apenas. Primeiro mediria quem ainda usa o contrato antigo, ofereceria convivencia temporária com o novo formato e só removeria depois que os consumidores criticos tivessem migrado e o uso residual estivesse controlado.”

Depreciação madura não pega consumidor de surpresa. Ela remove surpresa antes de remover suporte.

Contrato antigo só pode morrer quando o ecossistema já aprendeu a viver sem ele.