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.
O caminho de uma consulta
Seção intitulada “O caminho de uma consulta”- O CEP é validado (
01310100ou01310-100). Se for inválido, lançaInvalidCepErrorsem fazer nenhuma requisição. - Se o cache estiver ligado e o CEP já estiver nele, o endereço volta na hora.
- Os providers são tentados na ordem em que você os passou. Quem estiver com o circuito aberto é pulado.
- Cada tentativa tem um timeout. Com retry ligado, o mesmo provider é repetido antes de passar para o próximo.
- O primeiro que responder vence, e o resultado traz o nome dele em
provider.
Circuit breaker
Seção intitulada “Circuit breaker”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 conta como falha
Seção intitulada “O que conta como falha”| 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.
Estado dos circuitos
Seção intitulada “Estado dos circuitos”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.