Validación y gestión de errores

Una API se juzga por sus respuestas de fallo mucho más que por sus respuestas de éxito. El camino nominal es fácil: se escribió primero, se probó primero, se demostró primero. Los errores, en cambio, llegan a producción, en casa de un cliente que usted no conoce, en una situación que nadie había previsto, y es entonces cuando se revela la calidad de la API.

El síntoma clásico es un catálogo de incoherencias. Un identificador inexistente devuelve 500 con una página HTML de error de Spring. Un campo obligatorio ausente devuelve 400 con una estructura por defecto de Spring ilegible. Un conflicto de negocio devuelve 200 con {"succes": false}. Un desarrollador con prisa añade un try/catch en un controlador, otro añade @ResponseStatus en una excepción, un tercero devuelve un Map. Seis meses después, el equipo cliente ha escrito código distinto para cada endpoint y nadie se atreve ya a cambiar nada.

La salida de este callejón consiste en dos decisiones. Primero, validar las entradas en el borde de la aplicación, de forma declarativa, para que ningún dato dudoso llegue al servicio. Después, centralizar en un único punto la traducción de las excepciones a respuestas HTTP, con un formato único. Spring 6 proporciona ese formato: ProblemDetail, la implementación de la RFC 9457.