Expressのルーティングとexpress.Router()の使い方

Expressのルーティングは、HTTPメソッドとパスをハンドラー関数に結びつけます。app.get('/users', handler) は /users へのGETリクエストに答え、app.post()、app.put()、app.delete() はほかのメソッドで同じことをします。/users/:id のようにコロンで始まるセグメントはルートパラメーターで、その値は req.params に入ります。アプリが大きくなっても整理しておけるように、関連するルートは express.Router() にまとめ、app.use('/api', router) でプレフィックスの下にマウントします。

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

const users = [
    { id: 1, name: 'Ada' },
    { id: 2, name: 'Linus' },
];
let nextId = 3;

app.get('/users', (req, res) => {
    res.json(users);
});

// GET /users/2
app.get('/users/:id', (req, res) => {
    const user = users.find((u) => u.id === Number(req.params.id));
    if (!user) return res.status(404).json({ error: 'User not found' });
    res.json(user);
});

app.post('/users', (req, res) => {
    const user = { id: nextId++, name: req.body.name };
    users.push(user);
    res.status(201).json(user);
});

app.delete('/users/:id', (req, res) => {
    const index = users.findIndex((u) => u.id === Number(req.params.id));
    if (index === -1) return res.status(404).json({ error: 'User not found' });
    users.splice(index, 1);
    res.status(204).end();
});

app.listen(3000);

GET /users/2 は {"id":2,"name":"Linus"} を返します。ルートパラメーターは常に文字列なので、ハンドラーは Number(req.params.id) で比較しています。ボディを {"name": "Grace"} にして POST /users を送ると 201 が返ります。続けて DELETE /users/1 と GET /users を送ると、リストが変わるのがわかります。

プレフィックス付きのexpress.Router()

ルーターは、自分のルートとミドルウェアを持つ小さなアプリです。パスは相対的で、/api/books にマウントしたルーターの中で /:id と書いたルートは /api/books/:id に答えます。実際のプロジェクトでは、ルーターはそれぞれ自分のファイルに置き、最後に module.exports = router と書きます。

const express = require('express');

// routes/books.js
const books = express.Router();
const list = [{ id: 1, title: 'Dune' }];

books.get('/', (req, res) => {
    res.json(list);
});

books
    .route('/:id')
    .get((req, res) => {
        res.json(list.find((b) => b.id === Number(req.params.id)) ?? null);
    })
    .put((req, res) => {
        res.json({ updated: req.params.id });
    })
    .delete((req, res) => {
        res.json({ deleted: req.params.id });
    });

// server.js
const app = express();
app.use('/api/books', books);

// GET /api/books/1
app.listen(3000);

GET /api/books/1 は {"id":1,"title":"Dune"} を返します。router.route('/:id') はパスを一度だけ書き、メソッドごとのハンドラーをチェーンでつなぎます。PUT /api/books/1 を送ると {"updated":"1"} が返ります。マウントするパスを /v2/books に変えると、同じルーターがそこで答えるようになります。

ルートの順番：最初にマッチしたものが勝つ

Expressは登録した順にルートを試し、最初にレスポンスを送ったところで止まります。パラメーターのルートはその位置に来るものを何でも受け取るので、その後に登録した固定のパスには決して届きません。

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

app.get('/users/:id', (req, res) => {
    res.json({ route: '/users/:id', id: req.params.id });
});

app.get('/users/new', (req, res) => {
    res.json({ route: '/users/new' });
});

// Runs only when no route above answered.
app.use((req, res) => {
    res.status(404).json({ error: `Cannot ${req.method} ${req.path}` });
});

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

GET /users/new は {"route":"/users/:id","id":"new"} を返します。パラメーターのルートが先に登録されていて、それを受け取ってしまったからです。/users/new のルートを /users/:id より上に移して実行し直すと、{"route":"/users/new"} が返ります。続けて GET /books を送ると、一番下の404ハンドラーに届きます。

404ハンドラー

Expressはマッチしないリクエストに、Cannot GET /books という独自のHTMLページで答えます。APIならたいていJSONを返したいので、上のブロックのように、パスなしの app.use() を最後のルートとして追加します。これは、それより前のすべてのルートがリクエストを次に回したときだけ実行されます。ハンドラーが投げたエラーは別の話で、引数が4つの専用ハンドラーを使います。Expressのエラー処理で扱っています。

Express 5のルートパス

Express 5ではパスの書き方が変わりましたが、ネット上のコード例の多くはExpress 4向けに書かれています。

* だけ、あるいはパラメーターの後の ? は、ルートを登録した時点で TypeError を投げるので、アプリが起動しません。

よくある間違い

404ハンドラーを最初に登録する。 パスなしの app.use() はすべてにマッチするので、どのリクエストも404になります。一番下に置きましょう。

プレフィックスが取り除かれることを忘れる。 /api にマウントしたルーターの中では、req.path に /api は含まれません。フルパスが必要なら req.originalUrl を使います。

パラメーターを数値と比較する。 req.params.id は文字列の '1' なので、req.params.id === 1 は常にfalseです。