re:re:actable
Урок 042 минуты чтения

Как сделать единый обработчик ошибок и 404?

На этой странице
Кратко

Маршруты не должны вручную собирать один и тот же JSON ошибки. Прикладная ошибка описывает статус и код, а общий обработчик превращает её в HTTP-ответ.

Вопрос

Как сделать в Express единый обработчик ошибок и ответ 404? Чем ожидаемая ошибка отличается от неизвестной?

Класс прикладной ошибки

// src/errors/app-error.ts
export class AppError extends Error {
  constructor(
    public readonly status: number,
    public readonly code: string,
    message: string,
    public readonly details?: unknown,
  ) {
    super(message);
  }
}

Применение:

if (!user) {
  throw new AppError(404, "USER_NOT_FOUND", "Пользователь не найден");
}

Обработчик 404

404 — это не техническая ошибка Express. Просто ни один маршрут не завершил запрос.

import type { RequestHandler } from "express";
 
export const notFoundHandler: RequestHandler = (request, response) => {
  response.status(404).json({
    error: {
      code: "ROUTE_NOT_FOUND",
      message: `Маршрут ${request.method} ${request.path} не найден`,
    },
  });
};

Общий обработчик

import type { ErrorRequestHandler } from "express";
import { ZodError } from "zod";
import { AppError } from "../errors/app-error.js";
 
export const errorHandler: ErrorRequestHandler = (
  error,
  request,
  response,
  next,
) => {
  if (response.headersSent) {
    next(error);
    return;
  }
 
  if (error instanceof ZodError) {
    response.status(400).json({
      error: {
        code: "VALIDATION_ERROR",
        message: "Проверь данные запроса",
        details: error.issues,
      },
    });
    return;
  }
 
  if (error instanceof AppError) {
    response.status(error.status).json({
      error: {
        code: error.code,
        message: error.message,
        details: error.details,
      },
    });
    return;
  }
 
  console.error(error);
 
  response.status(500).json({
    error: {
      code: "INTERNAL_ERROR",
      message: "Внутренняя ошибка сервера",
    },
  });
};

Порядок подключения

app.use("/api", apiRouter);
app.use(notFoundHandler);
app.use(errorHandler);

Что записывать в журнал

На сервере полезны:

  • полная ошибка и стек;
  • идентификатор запроса;
  • метод и путь;
  • пользователь, если он известен;
  • время и окружение.

Клиенту эти подробности не отправляются.

Что важно помнить

  • Класс AppError хранит HTTP-статус и машинный код ошибки (USER_NOT_FOUND).
  • Неизвестная ошибка превращается в 500 с общим сообщением, подробности уходят в журнал.
  • Обработчик 404 ставится после всех маршрутов, обработчик ошибок — самым последним.
  • Ошибки проверки Zod удобно превращать в 400 / 422 в одном месте, а не в каждом маршруте.

Мини-шпаргалка

  • Ожидаемые ошибки описывай через AppError.
  • Неизвестная ошибка возвращает 500.
  • 404 размещается после маршрутов.
  • Обработчик ошибок размещается последним.
  • Внутренние подробности записываются на сервере, а не отправляются клиенту.

Документация

Express: Error handling.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам