A formatação de erros com http-error-kit é crucial para o desenvolvimento de APIs consistentes e fáceis de usar. Lidar com erros pode parecer algo secundário, mas APIs com diversos formatos de erro causam muita dor de cabeça. Uma estratégia padronizada facilita a integração e melhora a experiência do desenvolvedor.
## A Importância da Formatação de Erros com http-error-kit
No primeiro artigo, estabelecemos um formato global de erros para microserviços usando http-error-kit e @wthek/express-middleware. Embora um formato global garanta a consistência, diferentes tipos de erros podem exigir estruturas exclusivas, dependendo de sua natureza.
Por exemplo:
* Erros de Validação → Necessitam de detalhes específicos do campo.
* Erros de Autenticação → Devem indicar requisitos de reautenticação.
* Erros de Banco de Dados → Podem precisar de informações de query debugging.
Em vez de aplicar uma abordagem “tamanho único”, criaremos classes de erro personalizadas com formatadores no nível da instância para manter a consistência em toda a API, permitindo flexibilidade.
Por que a formatação no nível da instância é importante
Um formato global de erro é ótimo para consistência em alto nível, mas diferentes tipos de erro devem ter variações estruturadas.
Considere este exemplo:
Cenário: API sem formatação no nível da instância
Imagine uma resposta de API sem formatação específica:
{
"errorCode": 400,
"errorMessage": "Validation failed",
"errorDetails": { "field": "email" },
"timestamp": "2025-03-10T12:00:00.000Z"
}
Essa estrutura é genérica, mas e se o consumidor da API precisar de erros específicos do campo para melhor feedback da interface do usuário?
Em vez disso, devemos permitir diferentes formatos para diferentes classes de erro, mantendo uma estrutura de API ampla para tratamento de erros comuns.
Passo 1: Criando Classes de Erro Personalizadas com Formatação no Nível da Instância
Pense na formatação no nível da instância como dar a cada tipo de erro seu próprio padrão – erros de validação, falhas de autenticação e problemas de servidor, todos vestidos em um formato estruturado e previsível.
Em vez de usar o formatador global, podemos estender o http-error-kit para definir tipos de erro personalizados com seus próprios formatos.
Definindo uma classe de erro de validação personalizada
Vamos criar uma classe de erro de validação personalizada para lidar com erros de entrada do usuário. Isso nos permite fornecer mensagens de erro mais detalhadas e específicas para cada campo.
import { KitHttpError } from "http-error-kit";
import { BAD_REQUEST } from 'http-response-status-code';
// Define the instance-level formatter
const formatter = (statusCode, message, details, ...args) => ({
type: "VALIDATION_ERROR",
status: statusCode,
message,
fields: details,
timestamp: new Date().toISOString(),
});
class ValidationError extends KitHttpError {
constructor(message: string, fieldErrors: Record<string, string>, ...args) {
super(BAD_REQUEST, message, fieldErrors, ...args);
this.setFormatter(formatter); // Apply custom formatting
}
}
Agora, quando lançamos um ValidationError, ele segue um formato personalizado:
throw new ValidationError("Invalid Input", { email: "Email is required" });
Saída de resposta:
{
"type": "VALIDATION_ERROR",
"status": 400,
"message": "Invalid Input",
"fields": { "email": "Email is required" },
"timestamp": "2025-03-10T12:00:00.000Z"
}
Passo 2: Usando @wthek/express-middleware para Lidar com Erros Personalizados
Agora, vamos integrar as classes de erro personalizadas em nosso microserviço Express:
import express from "express";
import { KitExpressMiddleware } from "@wthek/express-middleware";
import { ValidationError } from "./errors/ValidationError";
const app = express();
// Example Route
app.post("/register", (req, res, next) => {
const email = req.body.email;
if (!email) {
next(new ValidationError("Invalid Input", { email: "Email is required" }));
}
});
// Error Handling Middleware
app.use(KitExpressMiddleware());
app.listen(3000, () => console.log("Server running on port 3000"));
Saída de resposta (quando o e-mail está faltando):
{
"type": "VALIDATION_ERROR",
"status": 400,
"message": "Invalid Input",
"fields": { "email": "Email is required" },
"timestamp": "2025-03-10T12:00:00.000Z"
}
Aprimorando a Formatação de erros com http-error-kit
Para melhorar ainda mais a experiência do desenvolvedor, considere adicionar detalhes de contexto aos erros, como IDs de rastreamento ou informações sobre o usuário que fez a solicitação. Isso pode facilitar a depuração e o rastreamento de problemas.
Além disso, documentar claramente os formatos de erro esperados em sua documentação da API ajudará os desenvolvedores a entender como lidar com diferentes tipos de erros.
Formatação de Erros Consistente para APIs Mais Robustas
No primeiro artigo, configuramos um formato de erro global para consistência em toda a API.
Na Parte 2, adicionamos classes de erro personalizadas com formatadores no nível da instância, garantindo:
* Consistência em toda a API para tratamento de erros.
* Formatação personalizada por tipo de erro.
* Respostas de erro mais limpas e estruturadas.
Uma estratégia de erro padronizada não apenas ajuda sua equipe, mas também torna sua API uma delícia de integrar. Os desenvolvedores adoram consistência, e sua API deve entregar exatamente isso.
Essa abordagem mantém as APIs públicas previsíveis, permitindo formatos de erro específicos quando necessário. Com este sistema, seu microsserviço tem um sistema de tratamento de erros totalmente personalizável!
Primeira: Este conteúdo foi auxiliado por Inteligência Artificiado, mas escrito e revisado por um humano.
Segunda: Via dev.to