Saltar al contenido

Errores y excepciones de la API de Laravel: cómo devolver respuestas – Laravel Daily

Los proyectos basados ​​en API son cada vez más populares y son bastante fáciles de crear en Laravel. Pero hay un tema del que se habla menos: es el manejo de errores para varias excepciones. Los consumidores de API a menudo se quejan de que reciben un “error del servidor”, pero no mensajes valiosos. Entonces, ¿cómo manejar correctamente los errores de API? ¿Cómo devolverlos en forma “legible”?

Objetivo principal: código de estado + mensaje legible

Para las API, los errores correctos son incluso más importantes que para los proyectos de navegador solo web. Como personas, podemos comprender el error del mensaje del navegador y luego decidir qué hacer, pero para las API, generalmente son consumidas por otro software y no por personas, por lo que el resultado devuelto debe ser “legible por máquinas”. Y eso significa códigos de estado HTTP.

Cada solicitud a la API devuelve algún código de estado, para las solicitudes exitosas suele ser 200, o 2xx con XX como otro número.

Si devuelve una respuesta de error, no debe contener código 2xx, aquí están los más populares para errores:

Código de estado Significado
404 No encontrado (la página u otro recurso no existe)
401 No autorizado (no iniciado sesión)
403 Ha iniciado sesión pero el acceso al área solicitada está prohibido
400 Solicitud incorrecta (algo incorrecto con la URL o los parámetros)
422 Entidad no procesable (validación fallida)
500 Error general del servidor

Tenga en cuenta que si no especificamos el código de estado para la devolución, Laravel lo hará automáticamente por nosotros, y eso puede ser incorrecto. Por eso es aconsejable especificar códigos siempre que sea posible.

Además de eso, tenemos que cuidar mensajes legibles por humanos. Entonces, una buena respuesta típica debe contener un código de error HTTP y un resultado JSON con algo como esto:

Idealmente, debería contener aún más detalles, para ayudar al consumidor de API a lidiar con el error. Aquí hay un ejemplo de cómo la API de Facebook devuelve un error:

Por lo general, el contenido de “error” es lo que se muestra en el navegador o la aplicación móvil. Entonces eso es lo que leerán los humanos, por lo tanto, debemos cuidar eso para que sea claro y con tantos detalles como sea necesario.

Ahora, veamos consejos reales sobre cómo mejorar los errores de API.

Consejo 1. Cambie APP_DEBUG = false incluso localmente

Hay un escenario importante en .env archivo de Laravel – es APP_DEBUG que puede ser falso o cierto.

Si lo enciende como cierto, luego se mostrarán todos sus errores con todos los detalles, incluidos los nombres de las clases, tablas de base de datos, etc.

Es un gran problema de seguridad, por lo que en el entorno de producción se recomienda estrictamente configurarlo en falso.

Pero aconsejaría desactivarlo para proyectos de API incluso localmente, aquí está el por qué.

Al desactivar los errores reales, forzado pensar como un consumidor de API que recibiría solo “Error del Servidor” y no más información. En otras palabras, se verá obligado a pensar cómo manejar los errores y proporcionar mensajes útiles desde la API.

Consejo 2. Rutas no gestionadas: método alternativo

Primera situación: ¿qué pasa si alguien llama a una ruta API que no existe? Puede ser realmente posible si alguien incluso cometió un error tipográfico en la URL. De forma predeterminada, obtienes esta respuesta de la API:

Y es un mensaje correcto, al menos el código 404 se pasa correctamente. Pero puedes hacer un mejor trabajo y explicar el error con algún mensaje.

Para hacer eso, puede especificar Ruta :: respaldo () método al final de rutas / api.php, manejando todas las rutas que no coincidieron.

El resultado será la misma respuesta 404, pero ahora con un mensaje de error que dará más información sobre qué hacer con este error.

Consejo 3. Anular la excepción 404 ModelNotFoundException

Una de las excepciones más frecuentes es que no se encuentra algún objeto de modelo, normalmente lo lanza Modelo :: findOrFail ($ id). Si lo dejamos así, aquí está el mensaje típico que mostrará su API:

Es correcto, pero no es un mensaje muy bonito para mostrar al usuario final, ¿verdad? Por lo tanto, mi consejo es anular el manejo de esa excepción en particular.

Podemos hacer eso en aplicación / Excepciones / Handler.php (recuerde ese archivo, volveremos a él varias veces más tarde), en hacer() método:

Podemos detectar cualquier número de excepciones en este método. En este caso, devolvemos el mismo código 404 pero con un mensaje más legible como este:

darse cuenta: has notado un método interesante $ excepción-> getModel ()? Hay mucha información muy útil que podemos obtener del objeto $ exception, aquí hay una captura de pantalla de la función de autocompletar de PhpStorm:

Consejo 4. Capture tanto como sea posible en la validación

En los proyectos típicos, los desarrolladores no piensan demasiado en las reglas de validación, se apegan principalmente a las simples como “requerido”, “fecha”, “correo electrónico”, etc. Pero para las API es en realidad la causa más común de errores: que el consumidor publica datos no válidos luego las cosas se rompen.

Si no ponemos un esfuerzo adicional en la captura de datos incorrectos, entonces la API pasará la validación de back-end y arrojará un simple “Error del servidor” sin ningún detalle (lo que en realidad significaría un error de consulta de DB).

Veamos este ejemplo: tenemos un Tienda() método en Controller:

Nuestro archivo FormRequest aplicación / Http / Requests / StoreOfficesRequest.php contiene dos reglas:

Si pasamos por alto ambos parámetros y pasamos valores vacíos allí, la API devolverá un error bastante legible con 422 código de estado (este código es producido por defecto por falla de validación de Laravel):

Como puede ver, enumera todos los errores de campo, también menciona todos los errores de cada campo, no solo el primero que se detectó.

Ahora, si no especificamos esas reglas de validación y permitimos que la validación pase, aquí está el retorno de la API:

Eso es todo. Error del Servidor. No hay otra información útil sobre lo que salió mal, qué campo falta o es incorrecto. Por lo tanto, el consumidor de API se perderá y no sabrá qué hacer.

Así que repetiré mi punto aquí: por favor, intente captar tantas situaciones posibles como sea posible dentro de las reglas de validación. Verifique la existencia del campo, su tipo, valores mínimo-máximo, duplicación, etc.

Consejo 5. Generalmente, evite el error de servidor 500 vacío con Try-Catch

Continuando con el ejemplo anterior, los errores vacíos son lo peor cuando se usa API. Pero la cruda realidad es que cualquier cosa puede salir mal, especialmente en proyectos grandes, por lo que no podemos corregir o predecir errores aleatorios.

Por otro lado, ¡podemos atraparlos! Con el bloque PHP try-catch, obviamente.

Imagina este código de controlador:

Es un ejemplo ficticio, pero bastante realista. Buscar un usuario con correo electrónico, luego crear un registro y luego hacer algo con ese registro. Y en cualquier paso, puede suceder algo malo. El correo electrónico puede estar vacío, es posible que no se encuentre el administrador (o que se encuentre un administrador incorrecto), el método de servicio puede generar cualquier otro error o excepción, etc.

Hay muchas formas de manejarlo y usar try-catch, pero una de las más populares es tener un gran try-catch, con varias excepciones:

Como puede ver, podemos llamar abortar() en cualquier momento, y agreguemos un mensaje de error que queramos. Si hacemos eso en cada controlador (o en la mayoría de ellos), entonces nuestra API devolverá el mismo 500 que “Error del servidor”, pero con mensajes de error mucho más procesables.

Consejo 6. Maneje los errores de API de terceros detectando sus excepciones

En estos días, los proyectos web utilizan muchas API externas y también pueden fallar. Si su API es buena, proporcionarán una excepción y un mecanismo de error adecuados. (irónicamente, ese es el punto de todo este artículo), así que usémoslo en nuestras aplicaciones.

Como ejemplo, intentemos hacer una solicitud de curl Guzzle a alguna URL y capturar la excepción.

El código es simple:

Como habrás notado, la URL de Github no es válida y este repositorio no existe. Y si dejamos el código como está, nuestra API arrojará … adivina qué … Sí, “500 Server error” sin más detalles. Pero podemos detectar la excepción y brindar más detalles al consumidor:

Consejo 6.1. Cree sus propias excepciones

Incluso podemos ir un paso más allá y crear nuestra propia excepción, relacionada específicamente con algunos errores de API de terceros.

Luego, nuestro archivo recién generado aplicación / Excepciones / GithubAPIException.php se verá así:

Incluso podemos dejarlo vacío, pero aún así lanzarlo como excepción. Incluso la excepción nombre puede ayudar al usuario de la API a evitar errores en el futuro. Entonces hacemos esto:

No solo eso, podemos mover ese manejo de errores a aplicación / Excepciones / Handler.php archivo (¿recuerdas arriba?), así:

Notas finales

Entonces, aquí están mis consejos para manejar los errores de API, pero no son reglas estrictas. Las personas trabajan con errores de formas muy diferentes, por lo que puede encontrar otras sugerencias u opiniones, no dude en comentar a continuación y hablemos.

Finalmente, quiero animarte a hacer dos cosas, además del manejo de errores:

¿Te gustan nuestros artículos?
¡Consulta nuestros cursos en línea de Laravel!

Este contenido se publicó originalmente aquí.