Vai al contenuto

ADR-0002: Error handling con RFC 7807 ProblemDetail

Stato: Accettato Data: 2026-05-20

Contesto

Dobbiamo standardizzare il formato di risposta in caso di errore. Le opzioni:

  1. Body JSON ad-hoc — {"error": "...", "code": "..."} — semplice ma proprietario.
  2. Errori "Google JSON style" — {"error": {"code": 404, "message": "..."}}.
  3. RFC 7807 ProblemDetail — standard IETF (application/problem+json).

Decisione

Adottiamo RFC 7807 con org.springframework.http.ProblemDetail, gestito da un unico @RestControllerAdvice:

  • Standard interoperabile (SDK e client lo riconoscono).
  • Estendibile: proprietà custom (field, from, to, timestamp) senza rompere la spec.
  • Supportato nativamente da Spring 6.

Ogni eccezione di business ha il proprio handler con: - HTTP status appropriato - type URI canonico (https://federicocalo.dev/errors/<categoria>) - title umano - detail specifico dell'istanza - proprietà custom utili al debug

Conseguenze

Positive

  • Stesso formato per tutti gli errori → frontend deve gestire un solo schema.
  • I type URL possono diventare anchor a una pagina di documentazione dell'errore.
  • Spring lo serializza con il content-type corretto (application/problem+json).

Negative

  • Leggermente più verboso di un formato ad-hoc per casi triviali.
  • Gli sviluppatori devono ricordarsi di non leak-are stack trace nella prod (configurato in application-prod.yml).

Neutre

  • I client devono saper leggere application/problem+json — la maggior parte degli HTTP client moderni sì.

Alternative valutate

  • Formato custom — scartato: lock-in, ogni client deve adattarsi.
  • Google JSON style — scartato: meno standard, più verboso senza vantaggi.