Como usar os filtros de exceção do Nest.js para lidar com erros

Os filtros de exceção Nest.js fornecem uma forma de intercetar e tratar excepções globalmente ou por controlador.

A centralização da lógica de tratamento de erros permite que os desenvolvedores simplifiquem seus processos, consolidando todo o código relacionado a erros em um só lugar. Esta abordagem não só simplifica a resolução de problemas, como também permite uma apresentação mais organizada das mensagens de erro aos utilizadores finais. Ao utilizar filtros de exceção, os programadores podem gerir eficazmente os erros que ocorrem numa aplicação, fornecendo um mecanismo de resposta coeso que assegura a consistência em todo o sistema.

Tratamento de erros padrão no Nest.js

O Nest.js inclui um mecanismo de tratamento de exceções integrado que cuida das exceções não tratadas geradas pelo código do aplicativo.

De facto, quando uma exceção passa despercebida durante o tempo de execução na sua aplicação desenvolvida com a estrutura Nest.js, o sistema responde automaticamente com um código de estado HTTP 500 Internal Server Error juntamente com um payload JSON predefinido que contém informações sobre a ocorrência do erro. Este formato foi concebido para ser facilmente consumido pelos programadores, que podem facilmente localizar a causa do problema a partir dos detalhes fornecidos.

 {
  "statusCode": 500,
  "message": "Internal server error"
}

Se um objeto de erro lançado pelo seu código incluir um código de status e uma mensagem, o Nest.js utilizará esses valores em vez de fornecer a resposta padrão.

Para evitar o tratamento genérico de erros e, em vez disso, fornecer uma resposta mais informativa aos clientes, é importante gerenciar cuidadosamente todos os erros potenciais em seu aplicativo. Isso pode ser feito utilizando os filtros de exceção pré-existentes do Nest.js ou criando filtros personalizados adaptados às suas necessidades específicas.

Criando um filtro de exceções personalizado

Para ilustrar o procedimento de desenvolvimento de um filtro de exceções personalizado, tente construir um que possa tratar todas as exceções HTTP.

Considere começar com um documento intitulado “http.exception.ts” e, em seguida, incorporar nele as seguintes instruções de importação:

 import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
} from '@nestjs/common';

import { Request, Response } from 'express';

Essas importações têm as seguintes finalidades.

Um filtro de excepções, tal como implementado através desta interface, serve para capturar e tratar as excepções que ocorrem durante a execução do programa.

O decorador Catch significa uma designação para uma classe como um mecanismo de filtragem de excepções no âmbito da estrutura Nest.

A interface ArgumentsHost apresenta um conjunto de métodos que facilitam a aquisição de argumentos transmitidos a um determinado manipulador. Ao utilizar esta estrutura, é possível selecionar um contexto de execução adequado, como HTTP, RPC ou WebSockets, para extrair os referidos argumentos.

A HttpException representa a base de todas as excepções HTTP Nest, englobando uma estrutura normalizada para o tratamento de erros em aplicações Web.

os objectos de pedido e de resposta. O primeiro representa os pedidos de entrada do cliente, enquanto o segundo é utilizado para enviar respostas a esses pedidos.

Para implementar um filtro de exceção para tratar HttpException s em nosso aplicativo ASP.NET Core, podemos criar uma nova classe chamada HttpExceptionFilter . Essa classe deve herdar do ExceptionFilterAttribute e ser anotada com o atributo Catch para tratar exceções desse tipo.

 @Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {}

Em seguida, preencha a classe com este código:

 catch(exception: HttpException, host: ArgumentsHost) {
    // Get the response object from the arguments host
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();

    // Get the request object from the arguments host
    const request = ctx.getRequest<Request>();

    // Get the status code from the exception
    const status = exception.getStatus();

    // Send a JSON response using the response object
    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message:
        exception.message
       || exception.getResponse()['message']
       || 'Internal Server Error',
    });
}

A implementação atual adquire os parâmetros de solicitação e resposta da instância ArgumentsHost e analisa as exceções para obter dados pertinentes. O resultado é uma resposta organizada em formato JSON com conteúdo informativo sobre o erro que é encaminhado para o utilizador final.

Filtros de exceção de ligação

Tem a opção de aplicar um filtro de exceção ao nível de controladores individuais ou em toda a aplicação, dependendo do que melhor se adequa às suas necessidades.

Para aplicar universalmente um filtro de excepções global, comece por incorporar o filtro de excepções no seu ficheiro principal main.ts . Em seguida, apresente uma instanciação do seu filtro de excepções ao método app.useGlobalFilters() .

 // main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { HttpExceptionFilter } from './exception/http.exception';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Bind filter to the application
  app.useGlobalFilters(new HttpExceptionFilter());

  await app.listen(4050);
}

bootstrap();

Para associar uma exceção a um controlador, é necessário utilizar o decorador “UseFilters” juntamente com o filtro de exceção correspondente. O processo envolve a importação do decorador “UseFilters” e do filtro de exceção específico. Posteriormente, a classe do controlador deve ser anotada utilizando o decorador “@UseFilters”, passando também uma instância do filtro de exceção como argumento para o decorador.

 @Controller()
@UseFilters(new HttpExceptionFilter())
export class AppController {}

A localização em que um filtro é aplicado ditará a sua gama de capacidades de tratamento de erros. Se um filtro estiver ligado a um controlador específico, aplicar-se-á apenas a esse controlador em particular, enquanto um filtro para toda a aplicação abrangerá toda a aplicação.

Usando exceções incorporadas para lançar erros

O Nest.js oferece uma gama de categorias de exceções predefinidas que podem ser utilizadas para lançar erros, que são projetadas para simplificar o tratamento de erros e agilizar o desenvolvimento de aplicativos, fornecendo uma abordagem padronizada para gerenciar exceções de forma organizada.

De facto, é possível utilizar a classe NotFoundException para gerar um erro de código de estado 404 em resposta a pedidos que não podem ser satisfeitos pelo servidor. Esta exceção é normalmente utilizada quando é feita uma tentativa de acesso a um recurso ou página que não existe no servidor. Ao lançar esta exceção, o servidor pode indicar ao cliente que o conteúdo solicitado não está disponível e fornecer informações sobre o motivo pelo qual o pedido falhou.

   getUserById(id: number) {
    const user = users.find((user) => user.id === id);

    if (!user) {
      throw new NotFoundException({
        message: `User with id ${id} not found`,
      });
    }
  }

O segmento de código anterior utiliza uma expressão condicional para verificar se o utilizador especificado está presente. Em caso de ausência, levanta uma exceção 404 utilizando a classe NotFoundException e fornecendo uma mensagem correspondente como argumento.

Classes de exceção incorporadas comuns

As categorias de exceção predefinidas adicionais incluem, mas não se limitam a, os seguintes exemplos.

A BadRequestException é uma exceção especializada no desenvolvimento de software que representa uma resposta HTTP com um código de estado 400. Esta exceção é lançada quando o pedido de um cliente é considerado inválido ou mal formatado pelo servidor, tornando-o incapaz de ser processado. A principal implicação desta exceção é que o cliente deve ajustar o seu pedido em conformidade para retificar quaisquer erros ou irregularidades.

A classe UnauthorizedException lança uma exceção que significa acesso não autorizado, acompanhada de um código de estado HTTP 401. Esta exceção pode ser lançada em situações em que um utilizador não tenha sido autenticado ou não possua os privilégios necessários para aceder a um recurso específico.

A classe ForbiddenException representa uma exceção que significa acesso não autorizado, acompanhada de um código de estado HTTP 403. Esta exceção pode ser lançada em situações em que um utilizador tenha sido autenticado com êxito, mas não tenha as permissões necessárias para executar uma determinada operação.

A RequestTimeoutException é uma exceção baseada em Java que é lançada quando um pedido excede o tempo limite especificado, resultando num código de estado HTTP 408. Esta exceção pode ser utilizada pelos servidores para terminar pedidos que demoraram mais tempo do que o previsto a processar.

A classe ConflictException representa uma exceção que ocorre devido a um conflito no código de estado 409. Este tipo de exceção pode ser lançado quando o pedido do cliente entra em conflito com o estado atual do recurso que está a ser operado, por exemplo, ao tentar criar um recurso que já foi criado.

A InternalServerErrorException é um tipo de exceção que representa um erro imprevisto que ocorre na infraestrutura do lado do servidor, resultando na incapacidade de satisfazer a tarefa solicitada. Esta exceção específica tem um código de estado HTTP associado de 500 e deve ser utilizada sempre que surja um problema inesperado no lado do servidor que o impeça de satisfazer os pedidos do cliente.

Práticas recomendadas para o tratamento de erros no Nest.js

Para gerenciar erros com eficiência em um aplicativo Nest.js, é importante utilizar filtros de exceção que capturam exceções globais ou específicas de controladores individuais. Além disso, é possível estabelecer filtros de exceção personalizados para tipos de erro específicos.

Além disso, é crucial utilizar as classes de exceção incorporadas adequadas para lançar mensagens de erro precisas e significativas. Esta abordagem contribui substancialmente para melhorar a fiabilidade das suas aplicações Nest.js.