Expressのミドルウェアとは？next()の仕組みと使い方

Expressのミドルウェアは (req, res, next) というシグネチャを持つ関数で、リクエストが届いてからレスポンスが送られるまでの間に実行されます。それぞれのミドルウェアは req と res を読んだり変えたりでき、レスポンスを送ってリクエストを終わらせることも、next() を呼んで次の関数にリクエストを渡すこともできます。app.use(fn) はすべてのリクエストに対するミドルウェアを追加し、Expressは登録した順にすべてを実行します。

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

function logger(req, res, next) {
    req.startedAt = Date.now();
    console.log('1. logger:', req.method, req.url);
    next();
}

app.use(logger);

app.use((req, res, next) => {
    console.log('2. second middleware');
    next();
});

app.get('/', (req, res) => {
    console.log('3. route handler');
    res.json({ ok: true, tookMs: Date.now() - req.startedAt });
});

app.listen(3000);

どのリクエストでも、Consoleには3つのステップが順番に記録され、ルートはロガーが追加したプロパティ req.startedAt を読んでいます。GET /missing を送ってみてください。app.use() はすべてのパスにマッチするので2つのミドルウェアはやはりログを出し、その後、マッチするルートがないのでExpressは404を返します。

next()を忘れる

レスポンスも送らず next() も呼ばないミドルウェアは、リクエストを宙ぶらりんにします。クライアントはタイムアウトするまで待ち、ログには何も出ません。そのため、これはミドルウェアでよくあるバグです。上の logger から next(); を消して GET / をもう一度送ると、リクエストに返事が来なくなります。

ルールは単純です。ミドルウェアを通るどの道も、次のどれか1つで必ず終わらせます。

• 続けるなら next()
• エラーハンドラーへ飛ぶなら next(err)（Expressのエラー処理を参照）
• res.json() や res.status(401).send() のようなレスポンス

レスポンスを送った後に next() を呼ぶのもバグです。次のハンドラーが2回目のレスポンスを送ろうとし、Expressは ERR_HTTP_HEADERS_SENT を投げます。関数がそこで止まるように return res.status(401).json(...) と書きましょう。

リクエストを止める認証チェック

リクエストを拒否するミドルウェアは、自分でレスポンスを送り、next() は呼びません。ルートに追加の引数として渡せば、そのルートだけを守れます。

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

function requireApiKey(req, res, next) {
    if (req.get('x-api-key') !== 'secret123') {
        return res.status(401).json({ error: 'Missing or wrong API key' });
    }
    req.client = 'reporting-app';
    next();
}

app.get('/public', (req, res) => {
    res.json({ message: 'Anyone can read this' });
});

app.get('/admin/stats', requireApiKey, (req, res) => {
    res.json({ users: 42, caller: req.client });
});

// GET /admin/stats
app.listen(3000);

最初のリクエストには 401 と {"error":"Missing or wrong API key"} が返ります。リクエストバーでヘッダー x-api-key: secret123 を追加して送り直すと、今度は {"users":42,"caller":"reporting-app"} が返ります。/public ではチェックは実行されません。

ミドルウェアが動く範囲

順番も意味の一部です。ルートの後に登録したロガーは、そのルートが答えたリクエストを決して記録しません。レスポンスを送ったルートは next() を呼ばないからです。ログ、ボディのパース、CORSのようなアプリ全体のミドルウェアを最初に、次にルート、最後に404とエラーのハンドラーを登録しましょう。

組み込みミドルウェア

Expressには、app.use() で追加するミドルウェア関数がいくつか付属しています。ボディパーサーは req.body を埋めます。これがないと req.body は undefined です。

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

app.use(express.json());
app.use(express.urlencoded());

app.get('/', (req, res) => {
    res.send('Send POST /echo with a body');
});

app.post('/echo', (req, res) => {
    res.json({ type: req.get('content-type'), body: req.body });
});

app.listen(3000);

ボディ {"name": "Ada"} で POST /echo を送ると、返事に "body":{"name":"Ada"} が含まれます。express.json() の行を消して送り直すと、返事から body がなくなります。req.body が undefined になり、JSON.stringify はundefinedの値を省くからです。cors、helmet、morgan のようなパッケージもミドルウェアで、npm install して同じように app.use() に渡します。ファイルの配信についてはexpress.staticのページで扱っています。

よくある間違い

ミドルウェアを渡さずに呼んでしまう。 app.use(logger()) は起動時に logger を1回実行し、その戻り値を登録します。app.use(logger) と書きましょう（express.json() に括弧が付くのは、ミドルウェア関数を返すからです）。

ボディパーサーをルートの後に追加する。 ルートが先に動くので、req.body は undefined に見えます。

app.use('/admin', fn) が1つのパスだけにマッチすると思う。 /admin/users など /admin の下のすべてのパスで、すべてのメソッドに対して実行されます。1つのルートだけを守るなら、ミドルウェアを app.get('/admin', fn, handler) に渡します。