Урок 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размещается после маршрутов.- Обработчик ошибок размещается последним.
- Внутренние подробности записываются на сервере, а не отправляются клиенту.
Документация
Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.