Pular para o conteúdo

Como funciona

A unicep tem duas peças:

  • Provider: o adaptador de um serviço de CEP. Faz a chamada HTTP e converte a resposta para o objeto Address.
  • Unicep: recebe uma lista de providers, coloca um circuit breaker em cada um e tenta um por um até alguém responder.

Seu app chama o Unicep, que tenta o Provider 1, depois o Provider 2 e assim por diante, cada um com o seu circuit breaker, e devolve sempre o mesmo objeto Address.

  1. O CEP é validado (01310100 ou 01310-100). Se for inválido, lança InvalidCepError sem fazer nenhuma requisição.
  2. Se o cache estiver ligado e o CEP já estiver nele, o endereço volta na hora.
  3. Os providers são tentados na ordem em que você os passou. Quem estiver com o circuito aberto é pulado.
  4. Cada tentativa tem um timeout. Com retry ligado, o mesmo provider é repetido antes de passar para o próximo.
  5. O primeiro que responder vence, e o resultado traz o nome dele em provider.

Cada provider tem o seu circuit breaker, que conta as falhas seguidas:

Estado O que significa
closed Normal. As requisições passam.
open Depois de failureThreshold falhas seguidas (3 por padrão), o provider é pulado sem fazer requisição.
half-open Passado resetTimeoutMs (30 segundos por padrão), uma requisição de teste decide se o circuito fecha ou abre de novo.

Assim, um serviço fora do ar não atrasa as consultas: a unicep vai direto para o próximo.

O que aconteceu Conta no circuit breaker? O que a unicep faz
Erro de rede, timeout, HTTP 5xx ou 429, resposta inválida Sim Tenta o próximo provider
“CEP não encontrado” Não Tenta o próximo provider, porque a cobertura muda entre serviços
Cancelamento por AbortSignal Não Para e rejeita com o motivo do cancelamento

Se todos os que responderam disseram “não encontrado”, o erro é CepNotFoundError. Se nenhum conseguiu responder, é AllProvidersFailedError, com um erro por provider. Veja Erros.

unicep.status();
// [
// { name: 'viacep', circuit: 'closed' },
// { name: 'brasilapi', circuit: 'open' },
// ...
// ]

É o que a página de status usa para mostrar cada provider em tempo real.