req.params, req.query и req.body в Express

В Express req.params хранит значения именованных сегментов пути маршрута (/users/:id даёт req.params.id), req.query хранит строку запроса после ? (/search?q=node даёт req.query.q), а req.body хранит данные, отправленные в теле запроса. req.params и req.query заполняются при каждом запросе, а req.body остаётся undefined, пока его не прочитает парсер тела, например app.use(express.json()). Значения в params и query всегда строки.

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

app.get('/users/:userId/posts', (req, res) => {
    res.json({ params: req.params, query: req.query });
});

app.post('/users/:userId/posts', (req, res) => {
    res.status(201).json({ params: req.params, body: req.body });
});

// GET /users/7/posts?sort=new&limit=2
app.listen(3000);

Первый запрос отвечает {"params":{"userId":"7"},"query":{"sort":"new","limit":"2"}}. Обратите внимание на кавычки: 7 и 2 это строки, поэтому преобразуйте их через Number(), прежде чем считать или сравнивать с числами. Теперь переключите метод на POST, оставьте путь /users/7/posts и отправьте тело {"title": "Hello", "draft": true}: ответ будет 201 с "body":{"title":"Hello","draft":true}, где true настоящий boolean, потому что он пришёл из JSON.

req.params, req.query и req.body

У маршрута может быть несколько параметров, и каждое имя становится ключом req.params: /teams/:teamId/members/:memberId даёт оба id. Дефис или точка тоже их разделяют, поэтому /flights/:from-:to превращает /flights/LAX-SFO в { from: 'LAX', to: 'SFO' }.

req.query с повторяющимися и отсутствующими ключами

Ключ, который встречается дважды, становится массивом, а отсутствующий ключ равен undefined, поэтому задавайте опциям значение по умолчанию:

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

app.get('/products', (req, res) => {
    const page = Number(req.query.page ?? 1);
    const tags = [].concat(req.query.tag ?? []);
    res.json({ page, tags, raw: req.query });
});

// GET /products?tag=red&tag=sale
app.listen(3000);

Ответ: {"page":1,"tags":["red","sale"],"raw":{"tag":["red","sale"]}}. Отправьте GET /products?tag=red&page=3, и tags всё равно будет массивом, ["red"], потому что [].concat() превращает в массив и одну строку, и массив. Express 5 разбирает строку запроса простым парсером Node, поэтому ?filter[size]=m даёт ключ "filter[size]", а не вложенный объект; Express 4 делал его вложенным.

req.body нужен express.json()

Node отдаёт тело потоком байтов. express.json() читает его, разбирает и заполняет req.body, но только если у запроса Content-Type: application/json. HTML-формы отправляют application/x-www-form-urlencoded, для этого нужен express.urlencoded().

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

app.post('/signup', (req, res) => {
    const { email, name } = req.body ?? {};
    if (!email) {
        return res.status(400).json({ error: 'email is required' });
    }
    res.status(201).json({ email, name: name ?? 'anonymous' });
});

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

app.listen(3000);

Отправьте POST /signup с телом {"email": "ada@example.com"}, и вы получите 201 с {"email":"ada@example.com","name":"anonymous"}. Отправьте пустое тело, и получите 400. ?? {} здесь важен: без него деструктуризация undefined выбрасывает TypeError на любом запросе без JSON-тела. Для настоящей проверки формы и типов используйте библиотеку схем, например zod.

req.headers и req.get()

req.headers это объект со всеми заголовками запроса, имена в нижнем регистре. req.get(name) читает один заголовок без учёта регистра, поэтому req.get('Content-Type') и req.get('content-type') возвращают одно и то же. Ещё несколько свойств, которые вам пригодятся:

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

app.get('/whoami', (req, res) => {
    res.json({
        method: req.method,
        path: req.path,
        originalUrl: req.originalUrl,
        agent: req.get('User-Agent') ?? null,
        token: req.get('authorization') ?? null,
    });
});

// GET /whoami?debug=1
app.listen(3000);

path равен /whoami, а originalUrl равен /whoami?debug=1. Добавьте в строке запроса заголовок Authorization: Bearer abc и отправьте снова: token станет "Bearer abc". Внутри router'а, подключённого через app.use('/api', router), req.path теряет префикс /api, а req.originalUrl его сохраняет (подключение объясняет статья Маршрутизация в Express).

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

Чтение req.body в GET-запросе. Браузеры и большинство клиентов не отправляют тело с GET. Передавайте опции GET в строке запроса.

Проверка флага из query на истинность. ?admin=false даёт строку 'false', а она truthy, поэтому if (req.query.admin) проходит. Сравнивайте строки: req.query.admin === 'true'.

JSON без заголовка. Клиент, который отправляет JSON как text/plain, получает req.body === undefined. Задайте на клиенте Content-Type: application/json.