Xử lý lỗi trong Express: error middleware và lỗi async

Express xử lý lỗi bằng một middleware đặc biệt nhận bốn đối số, (err, req, res, next), và được đăng ký sau tất cả các route. Express chuyển đến đó mọi lỗi bị ném ra trong route, mọi lỗi bạn truyền vào next(err), và ở Express 5 là cả mọi promise bị reject từ handler async. Handler này quyết định status code và gửi một response lỗi duy nhất, nên phần còn lại của code chỉ cần ném lỗi (throw).

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 trả về 404 với {"error":"No user with id 99"}, và Console hiện dòng log từ error handler. Gửi GET /users/1 thì route trả lời bình thường; error handler chỉ chạy khi có gì đó sai.

Những lỗi Express tự bắt giúp bạn

Có ba cách để đi từ một route đến error handler, và ở Express 5 cả ba đều hoạt động như nhau:

// 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 trả về 500 với {"error":"Rejected in an async route"}; GET /sync và GET /next cũng kết thúc ở cùng handler đó với thông báo riêng của từng route. Giờ hãy xóa next khỏi danh sách tham số của error handler rồi gửi lại GET /sync: với ba tham số, Express coi nó là middleware thường, bỏ qua nó và trả về trang lỗi HTML mặc định.

Lỗi async: Express 5 và Express 4

Route /async chạy được là vì Express 5 bắt được promise bị reject. Express 4 thì không: lỗi trở thành unhandled rejection và request bị treo.

Với Express 4, hãy bọc từng handler async hoặc cài package 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);
}));

Hàng cuối cùng giống nhau ở cả hai phiên bản: Express không thể thấy lỗi bị ném ra trong một callback mà nó không gọi. Hãy chuyển các API dạng callback sang promise (phần lớn Node đều có bản promise, chẳng hạn fs/promises) rồi await chúng.

Handler 404 và lỗi JSON thống nhất

API dễ dùng hơn khi mọi lỗi có cùng một dạng. Gắn status cho lỗi, biến các route không khớp thành lỗi 404, và để một handler định dạng tất cả:

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 không khớp route nào, nên handler 404 biến nó thành lỗi và câu trả lời là {"error":"Cannot GET /nope","status":404}. Gửi GET /users/99 thì lỗi do route ném ra cũng có cùng dạng. Gửi POST /users với body {"name": }: express.json() không parse được và gọi next() với một lỗi có status là 400, nên câu trả lời là {"error":"Unexpected token '}', \"{\"name\": }\" is not valid JSON","status":400}.

Đừng để lộ stack trace

Thông báo lỗi từ HttpError của bạn được viết cho client đọc. Thông báo và stack từ mọi thứ khác (driver cơ sở dữ liệu, một lỗi gõ nhầm ném ra TypeError) có thể làm lộ đường dẫn tệp, câu truy vấn và phiên bản thư viện. Handler ở trên gửi Internal server error cho mọi lỗi 5xx và ghi lỗi thật vào log trên server. Dòng if (res.headersSent) return next(err); xử lý lỗi xảy ra khi một phần response đã được gửi đi: lúc đó cách an toàn duy nhất là để Express đóng kết nối.

Handler mặc định của Express dựa vào NODE_ENV: nó đưa stack trace vào trang HTML trừ khi NODE_ENV là production. Hãy đặt biến này trên server production (NODE_ENV=production node server.js), nhưng đừng chỉ trông vào nó: một handler tự viết không bao giờ gửi err.stack sẽ an toàn hơn.

Lỗi thường gặp

Đăng ký error handler trước các route. Express chỉ chuyển lỗi về phía sau, nên một handler đặt phía trên route sẽ không bao giờ thấy lỗi của route đó. Đặt nó ở cuối cùng, sau handler 404.

Bắt lỗi rồi không làm gì cả. Một khối try/catch chỉ ghi log sẽ để request bị treo. Trong catch, hãy gọi next(err), ném lỗi lại, hoặc gửi response.

Gửi hai response. Ném lỗi sau khi đã gọi res.json() khiến error handler cố gửi thêm lần nữa. Kiểm tra res.headersSent như trong ví dụ.

Để hiểu middleware thường và next() hoạt động thế nào, xem middleware trong Express.