Express 的 req.params、req.query 和 req.body 详解

在 Express 中，req.params 保存路由路径中命名段的值（/users/:id 对应 req.params.id），req.query 保存 ? 后面的查询字符串（/search?q=node 对应 req.query.q），req.body 保存请求体中发送的数据。每个请求都会填充 req.params 和 req.query，但在 app.use(express.json()) 这样的请求体解析器读取它之前，req.body 一直是 undefined。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 是真正的布尔值，因为它来自 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。?? {} 很重要：没有它，任何没有 JSON 请求体的请求都会在解构 undefined 时抛出 TypeError。要真正校验结构和类型，请使用 zod 这类 schema 库。

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"。在用 app.use('/api', router) 挂载的路由器里，req.path 会去掉 /api 前缀，而 req.originalUrl 会保留它（挂载的内容见 Express 路由）。

常见错误

在 GET 请求中读取 req.body。 浏览器和大多数客户端在 GET 请求中都不发送请求体。把 GET 的选项放进查询字符串。

用真值判断查询参数。 ?admin=false 得到的是字符串 'false'，它是真值，所以 if (req.query.admin) 会通过。应该比较字符串：req.query.admin === 'true'。

发送 JSON 却没有设置请求头。 以 text/plain 提交 JSON 的客户端会得到 req.body === undefined。在客户端设置 Content-Type: application/json。