Обработка ошибок в Express: error middleware и async

Express обрабатывает ошибки специальным middleware, который принимает четыре аргумента, (err, req, res, next), и регистрируется после всех ваших маршрутов. Express передаёт ему каждую ошибку, выброшенную внутри маршрута, каждую ошибку, переданную в next(err), а в Express 5 ещё и каждый отклонённый промис из async-обработчика. Обработчик выбирает код статуса и отправляет один ответ с ошибкой, так что остальной код может просто выбрасывать ошибки.

const express = require('express');
const app = express();

const users = [{ id: 1, name: 'Ada' }];

app.get('/users/:id', (req, res) => {
    const user = users.find((u) => u.id === Number(req.params.id));
    if (!user) {
        const err = new Error(`No user with id ${req.params.id}`);
        err.status = 404;
        throw err;
    }
    res.json(user);
});

// The error handler: four arguments, after the routes.
app.use((err, req, res, next) => {
    console.log('error handler:', err.message);
    res.status(err.status ?? 500).json({ error: err.message });
});

// GET /users/99
app.listen(3000);

GET /users/99 отвечает 404 с {"error":"No user with id 99"}, а в Console видна строка из обработчика ошибок. Отправьте GET /users/1, и маршрут ответит как обычно; обработчик ошибок срабатывает, только когда что-то пошло не так.

Ошибки, которые Express ловит за вас

Из маршрута до обработчика ошибок можно добраться тремя способами, и в Express 5 все три работают одинаково:

// Each route throws on purpose to reach the error handler.
const express = require('express');
const app = express();

app.get('/sync', (req, res) => {
    throw new Error('Thrown in a route');
});

app.get('/next', (req, res, next) => {
    next(new Error('Passed to next()'));
});

app.get('/async', async (req, res) => {
    await new Promise((resolve) => setTimeout(resolve, 10));
    throw new Error('Rejected in an async route');
});

app.use((err, req, res, next) => {
    res.status(500).json({ error: err.message });
});

// GET /async
app.listen(3000);

GET /async отвечает 500 с {"error":"Rejected in an async route"}; GET /sync и GET /next попадают в тот же обработчик со своими сообщениями. Теперь уберите next из параметров обработчика ошибок и снова отправьте GET /sync: с тремя параметрами Express считает его обычным middleware, пропускает и отвечает своей стандартной HTML-страницей ошибки.

Async-ошибки: Express 5 и Express 4

Маршрут /async работает, потому что Express 5 ловит отклонённый промис. Express 4 этого не делал: ошибка превращалась в необработанное отклонение, и запрос зависал.

В Express 4 оборачивайте каждый async-обработчик или установите пакет express-async-errors:

// Express 4 only
const asyncHandler = (fn) => (req, res, next) =>
    Promise.resolve(fn(req, res, next)).catch(next);

app.get('/users/:id', asyncHandler(async (req, res) => {
    const user = await db.findUser(req.params.id);
    res.json(user);
}));

Последняя строка таблицы одинакова в обеих версиях: Express не видит ошибку, выброшенную в callback'е, который вызывал не он. Превращайте callback API в промисы (у большей части Node есть версия на промисах, например fs/promises) и ждите их через await.

Обработчик 404 и единый формат JSON-ошибки

API удобнее, когда у всех ошибок одинаковая форма. Дайте ошибкам status, превращайте несовпавшие маршруты в ошибку 404, а форматирует их все один обработчик:

const express = require('express');
const app = express();
app.use(express.json());

class HttpError extends Error {
    constructor(status, message) {
        super(message);
        this.status = status;
    }
}

const users = [{ id: 1, name: 'Ada' }];

app.get('/users/:id', (req, res) => {
    const user = users.find((u) => u.id === Number(req.params.id));
    if (!user) throw new HttpError(404, `No user with id ${req.params.id}`);
    res.json(user);
});

app.post('/users', (req, res) => {
    if (!req.body?.name) throw new HttpError(400, 'name is required');
    res.status(201).json({ id: 2, name: req.body.name });
});

// 404: no route matched.
app.use((req, res, next) => {
    next(new HttpError(404, `Cannot ${req.method} ${req.path}`));
});

app.use((err, req, res, next) => {
    if (res.headersSent) return next(err);
    const status = err.status ?? 500;
    if (status >= 500) console.log(err);
    res.status(status).json({
        error: status >= 500 ? 'Internal server error' : err.message,
        status,
    });
});

// GET /nope
app.listen(3000);

GET /nope не совпадает ни с одним маршрутом, поэтому обработчик 404 превращает его в ошибку, и ответ такой: {"error":"Cannot GET /nope","status":404}. Отправьте GET /users/99, и ошибка, выброшенная маршрутом, получит ту же форму. Отправьте POST /users с телом {"name": }: express.json() не может его разобрать и вызывает next() с ошибкой, у которой status равен 400, поэтому ответ будет {"error":"Unexpected token '}', \"{\"name\": }\" is not valid JSON","status":400}.

Не показывайте stack trace

Сообщения ваших собственных HttpError написаны для клиента. Сообщения и стеки всего остального (драйвера базы данных, опечатки, из-за которой вылетел TypeError) могут раскрыть пути к файлам, запросы и версии библиотек. Обработчик выше отправляет Internal server error для любой ошибки 5xx, а настоящую ошибку логирует на сервере. if (res.headersSent) return next(err); покрывает ошибку, случившуюся после того, как часть ответа уже отправлена: тогда единственный безопасный ход это дать Express закрыть соединение.

Стандартный обработчик Express смотрит на NODE_ENV: он включает stack trace в свою HTML-страницу, если NODE_ENV не равен production. Задайте его на продакшен-сервере (NODE_ENV=production node server.js), но не полагайтесь на это: свой обработчик, который никогда не отправляет err.stack, надёжнее.

Частые ошибки

Обработчик ошибок зарегистрирован до маршрутов. Express передаёт ошибки только вперёд, поэтому обработчик выше маршрута никогда не увидит его ошибки. Ставьте его последним, после обработчика 404.

Ошибку поймали и ничего с ней не сделали. try/catch, который только логирует, оставляет запрос висеть. В catch вызовите next(err), выбросьте ошибку снова или отправьте ответ.

Два ответа. Если выбросить ошибку после res.json(), обработчик ошибок попробует отправить ответ ещё раз. Проверяйте res.headersSent, как в примере.

Как работают обычный middleware и next(), читайте в статье Express middleware.