Pular para conteúdo

0012 — Exceções em pacote top-level

Decisão obsoleta — superada pela decisão 0030

Status: Obsoleto · Responsável: Gustavo Madruga · Atualizado em: 2026-09-14 · Decidido em: 2026-04-01

Contexto

As exceções de domínio (BadRequestException, ConflictException, NotFoundException, StorageIndisponivelException) são lançadas de qualquer camada: o ArquivoDetector rejeita nome temporário com BadRequestException, o storage sinaliza I/O com StorageIndisponivelException, os repositórios colidem com ConflictException. Se elas morassem dentro de um pacote de feature (processing/, storage/, api/), qualquer camada que as lançasse passaria a depender daquele pacote — criando ciclos arquiteturais.

Decisão

Manter as exceções de domínio num pacote top-level exception/, sem depender de nenhuma feature. Assim qualquer camada as lança sem introduzir dependência cruzada. O ArchitectureTest (ArchUnit) valida a ausência de ciclos entre os pacotes top-level.

Consequências

  • Cross-cutting sem ciclos: processing, storage, api, service lançam as mesmas exceções sem se acoplarem entre si.
  • As classes eram idênticas às do irmão bi-transporte-xls — candidatas diretas ao bi-commons.
  • Mapeamento para HTTP fica centralizado (o handler RFC 7807 traduz cada uma — ver 0015).

Atualização (spec 009 / ADR 0019): BadRequestException, ConflictException e NotFoundException foram extraídas para a lib br.com.xadm:xadm-comum-web (o "bi-commons" desta fatia) — seguem top-level (br.com.xadm.comum.web), lançáveis de qualquer camada, mesma propriedade anti-ciclo. Ficam locais as de domínio: StorageIndisponivelException (503, XLS) e ForbiddenException (403, bi_configuracao). A decisão desta ADR (top-level, não por feature) segue valendo para as duas locais.

Alternativas consideradas

  • Exceções dentro de cada feature: acopla quem lança ao pacote da feature e gera ciclos (barrados pelo ArchUnit). Descartado.
  • Só exceções padrão do Java/HTTP: perde a semântica de domínio (409 vs 400 vs 503) e o mapeamento uniforme. Descartado.

Correção 2026-09-14: superada pela 0030 (package-by-feature): a exceção local de storage mora em comum.exception, a base transversal que não depende de fatia.