O Que é um Breaking Change? Quando uma Atualização Quebra os Callers
Um breaking change é uma modificação que força a atualização de callers ou dados existentes, porque o uso antigo não funciona mais contra a nova versão.
Um breaking change é o oposto de backward compatibility. Ele remove, renomeia ou restringe algo de que os callers dependem, então qualquer coisa construída sobre o comportamento antigo falha até ser atualizada. Breaking changes não são proibidos, mas exigem coordenação, versionamento e um rollout deliberado, razão pela qual o CI se esforça para sinalizá-los cedo.
O que conta como breaking
Remover ou renomear um campo ou endpoint, tornar um campo opcional obrigatório, mudar um tipo, restringir a validação ou mudar o significado de um valor. Qualquer coisa que possa fazer uma chamada antes válida falhar, ou ser mal interpretada, é um breaking change.
Breaking versus não-breaking
- Não-breaking: adicionar um campo opcional, um novo endpoint, um novo caso de enum.
- Breaking: remover um campo, renomear uma rota, mudar um tipo.
- Sutil: restringir a validação ou mudar o comportamento padrão.
- O teste: algum caller existente deixaria de funcionar?
Por que são custosos
Um breaking change em uma interface compartilhada força todo consumer a atualizar, idealmente em lockstep, que é exatamente a coordenação que microservices e deploys independentes tentam evitar. Quanto mais consumers, maior o custo e maior o blast radius.
Pegando-os no CI
Com um contrato explícito, a pipeline pode fazer diff entre o antigo e o novo e falhar o build em um breaking change, para que ele não vá para produção por acidente. Este é o guardrail mais eficaz contra uma quebra não intencional chegar aos consumers.
Shipando um de propósito
Quando uma quebra é genuinamente necessária, o caminho seguro é uma nova versão: rodar antiga e nova lado a lado, migrar os consumers, então aposentar a antiga. A pipeline mantém ambas as versões testadas até o último consumer ter saído da antiga.
Perigo do deploy de versões mistas
Um breaking change deployado sem versionamento é mais perigoso durante a janela de versões mistas de um rolling deploy, quando os callers podem atingir qualquer uma das versões. Verificações de compatibilidade no CI são o que evitam que essa janela vire uma queda.
Principais conclusões
- Um breaking change faz os callers existentes falharem até serem atualizados.
- Adicionar costuma ser seguro; remover, renomear ou restringir costuma quebrar.
- O diff de contrato no CI é a melhor proteção contra shipar um por acidente.