Express.js 路由基础：怎么处理 GET/POST 请求与参数解析

在 Express.js 中，服务端开发最核心的工作之一就是匹配客户端请求并正确解析其携带的数据。无论是通过 URL 传递的资源标识和过滤条件，还是通过请求体提交的表单与 JSON 结构，Express 都提供了清晰的机制进行承接。本文将系统梳理 Express.js 中 GET 与 POST 路由的基础处理流程，重点拆解 req.params、req.query 与 req.body 三种参数的获取机制，并详细说明中间件在 POST 请求体解析中的必要性与常见错误排查。

一、Express 路由的核心概念与服务骨架

在 Web 开发中，路由（Routing）定义了应用程序如何响应客户端对特定端点的访问请求。一个端点由一个 URI 路径（例如 /api/books）和一个具体的 HTTP 请求方法（例如 GET、POST、PUT 或 DELETE）共同确定。

在 Express 中，每个路由结构都由方法调用绑定到应用实例上，其基础定义公式为：app.METHOD(PATH, HANDLER)。其中 app 为 Express 实例，METHOD 是小写的 HTTP 谓词，PATH 是服务端的相对路径，而 HANDLER 则是当路由命中后执行的回调函数，接收 req（请求对象）和 res（响应对象）。

// 引入 express 模块并创建服务实例
const express = require('express');
const app = express();
const PORT = 3000;

// 1. 基础 GET 路由示例
app.get('/', (req, res) => {
  res.send('Hello Express! 服务运行正常。');
});

// 2. 基础 POST 路由示例
app.post('/api/echo', (req, res) => {
  res.json({ status: 'success', message: '收到 POST 请求' });
});

// 监听端口启动服务
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

当客户端向服务器发起请求时，Node.js 底层的 HTTP 模块将网络包组装为原始数据流，而 Express 在此基础上扩展出 req 与 res。此时整个生命周期会按顺序穿过前置中间件、路由匹配引擎，最终进入业务处理函数。

二、GET 请求与 URL 传参：req.query 与 req.params

GET 请求主要用于从服务端安全地获取数据，按照 HTTP 协议规范，GET 请求不应当在请求体（Body）中包含业务数据。客户端想要向服务端传递信息，只能通过 URL 传递。Express 为此提供了两种截然不同的提取机制：req.query 和 req.params。

1. 查询字符串（Query String）：req.query

查询字符串是指位于 URL 问号 ? 之后的内容，多个键值对之间用 & 符号分隔。例如访问 /api/articles?category=tech&page=1&limit=10 时，Express 内部会自动解析这个查询字符串，并挂载在 req.query 对象上。

查询参数最适合用于数据的过滤、排序、关键词搜索以及分页控制。因为这些参数不是资源的固有标识，而是对结果集合的修饰。

// 查询参数处理示例
app.get('/api/articles', (req, res) => {
  // 解构出查询参数
  const { category, page = '1', limit = '10' } = req.query;

  // 注意：req.query 中的值都是 String 类型，计算时需显式转换
  const pageNum = parseInt(page, 10);
  const pageSize = parseInt(limit, 10);

  res.json({
    code: 200,
    filters: { category, pageNum, pageSize },
    data: []
  });
});

2. 动态路由路径参数（Route Parameters）：req.params

动态路径参数是将参数直接嵌入在 URL 路径本身的一部分。在定义路由时，使用冒号 :参数名 来声明占位符。例如定义 /users/:userId，当客户端请求 /users/1024 时，Express 会捕获匹配到的片段并赋值给 req.params.userId。

路径参数符合 RESTful 架构风格，最适合用于标识某个具体的、唯一的资源对象（例如特定 ID 的文章、指定编号的用户等）。

// 动态路径参数示例
app.get('/api/users/:userId/books/:bookId', (req, res) => {
  // 通过 req.params 直接提取 URL 中占位符对应的值
  const { userId, bookId } = req.params;

  res.json({
    message: '获取特定用户的特定书籍详情',
    userId: userId,
    bookId: bookId
  });
});

三、POST 请求与请求体解析：req.body 与中间件机制

POST 请求通常用于向服务器提交数据以创建新资源或执行状态变更（例如用户注册、提交订单、上传表单等）。这些数据不会暴露在 URL 中，而是放置在 HTTP 请求体（Body）内传输。

1. 为什么默认情况下 req.body 是 undefined？

许多初学者在写 Express 代码时常遇到一个典型问题：在 POST 路由处理函数中打印 req.body，控制台输出却是 undefined。

这是因为 Node.js 底层的 HTTP 请求体是以流（Stream）的形式分包异步传输的。Express 秉持极简核心的设计理念，默认不会自动缓冲并解析整个请求体。为了让 req.body 包含解析好的 JavaScript 对象，必须显式注册请求体解析中间件。

自 Express 4.16.0 起，Express 重新内置了常用解析器（基于 body-parser），开发者不再需要单独安装第三方依赖，直接调用 express.json() 和 express.urlencoded() 即可。

2. 解析 JSON 请求体：express.json()

当客户端（如 Axios、Fetch API、移动端或前端单页应用）发送请求头为 Content-Type: application/json 的数据时，服务端需要使用 express.json() 中间件进行拦截与反序列化。

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

// 必须在定义路由之前挂载此中间件！
app.use(express.json());

app.post('/api/users', (req, res) => {
  // 此时 req.body 已成功解析为普通 JavaScript 对象
  const { username, email, role } = req.body;

  if (!username || !email) {
    return res.status(400).json({ error: '用户名和邮箱为必填项' });
  }

  // 模拟数据保存成功返回 201 状态码
  res.status(201).json({
    id: 1001,
    username,
    email,
    role: role || 'user'
  });
});

3. 解析传统表单提交：express.urlencoded()

当用户通过传统 HTML <form method="POST"> 提交表单时，浏览器默认生成的请求头为 Content-Type: application/x-www-form-urlencoded。此时需使用 express.urlencoded() 中间件：

// extended: true 表示内部使用 qs 库解析，支持深层嵌套对象；false 则使用 querystring 原生模块
app.use(express.urlencoded({ extended: true }));

app.post('/submit-form', (req, res) => {
  const { nickname, bio } = req.body;
  res.send(`表单已接收，昵称：${nickname}`);
});

四、参数解析核心机制综合对比与选型指南

在实际项目架构中，合理选择参数传递途径对于 API 的清晰度、规范性以及安全性至关重要。下表全面对比了 Express 中四种常见参数获取方式的核心差异：

五、路由设计与工程实践注意事项

掌握了参数提取的基础后，在编写生产级代码时，还需要特别注意以下几个常见陷阱与规范：

1. 静态路由与通配路由的注册先后顺序

Express 的路由表是按注册代码出现的先后顺序从上到下执行匹配的。如果在动态参数路由之后定义了具体名称的静态路由，该静态路由将永远无法被命中。

// 错误示范：/users/:id 写在前面
app.get('/users/:id', (req, res) => { ... });
app.get('/users/profile', (req, res) => { ... }); // 永远无法命中！'profile' 会被当作 :id

// 正确做法：具体静态路径必须位于动态通配路径之前
app.get('/users/profile', (req, res) => {
  res.json({ role: 'current_user' });
});
app.get('/users/:id', (req, res) => {
  res.json({ userId: req.params.id });
});

2. 防御性校验与参数清洗

永远不要对客户端传入的数据做过度信任假设。即使前端做了表单校验，恶意请求依然可以直接通过 cURL 或脚本向接口提交非法 payload。

• 类型转换与有效性检查：针对 req.params 和 req.query 中的数字类型，检查 isNaN() 避免无效查询。
• 只解构允许写入的字段：避免直接执行 Model.create(req.body)，防止恶意客户端注入未经许可的权限字段（例如 role: 'admin'）。应显式解构提取需要的白名单字段。
• 防范 JSON 解析崩溃：如果客户端发送了格式畸形的 JSON 字符串，express.json() 默认会抛出 SyntaxError。在应用末尾应挂载全局错误处理中间件以优雅捕获并返回 400 状态码。

3. 使用 express.Router() 进行模块化拆分

随着项目路由增多，将所有代码堆砌在同一个 app.js 中会导致难以维护。应使用 express.Router() 按照业务领域将不同模块拆分到独立文件中：

// routes/users.js
const express = require('express');
const router = express.Router();

router.get('/', (req, res) => { /* 查询用户列表 */ });
router.get('/:id', (req, res) => { /* 查询单个用户 */ });
router.post('/', (req, res) => { /* 创建新用户 */ });

module.exports = router;

// app.js 主入口文件
const userRouter = require('./routes/users');
app.use('/api/users', userRouter);

通过理解 HTTP 请求的基本结构、正确配置请求体中间件，并依据具体业务语义在 req.params、req.query 与 req.body 之间做出恰当选型，即可构建出逻辑严谨、健壮可靠的 Express.js 后端服务。