Node.js / 系统课时
解析查询参数
解析查询参数
Node.js 收到请求后,req.url 提供请求目标中的路径和查询字符串。使用标准 URL API 可以把它拆成 pathname 与 searchParams,避免手工切割 ?、& 和 =,并能正确处理重复参数与 URL 编码。
学习目标
- 使用
URL解析请求路径和查询字符串 - 使用
URLSearchParams读取单值与重复查询参数 - 对数字参数和缺失参数进行显式校验
从请求地址创建 URL 对象
HTTP 服务里的 req.url 通常是类似 /search?q=node&limit=2 的相对请求目标,而 new URL() 解析相对地址时需要一个基准地址。只为了读取路径和查询参数时,可以使用固定基准 http://localhost,不必依赖客户端传来的 Host 头。
下面实现一个 /search 接口,读取关键词 q、数量 limit 和可重复出现的 tag 参数。
const http = require('node:http');
const server = http.createServer((req, res) => {
const url = new URL(req.url ?? '/', 'http://localhost');
if (url.pathname !== '/search') {
res.statusCode = 404;
res.setHeader('Content-Type', 'text/plain; charset=utf-8');
res.end('Not Found');
return;
}
const query = url.searchParams.get('q') ?? '';
const limitText = url.searchParams.get('limit') ?? '10';
const tags = url.searchParams.getAll('tag');
const limit = Number(limitText);
if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
res.statusCode = 400;
res.setHeader('Content-Type', 'application/json; charset=utf-8');
res.end(JSON.stringify({ error: 'limit must be an integer from 1 to 50' }));
return;
}
res.statusCode = 200;
res.setHeader('Content-Type', 'application/json; charset=utf-8');
res.end(JSON.stringify({ path: url.pathname, query, limit, tags }));
});
server.listen(3000, () => {
console.log('Server listening on http://localhost:3000');
});预期输出
Server listening on http://localhost:3000读取单个和重复参数
启动服务后请求:
curl "http://localhost:3000/search?q=node%20js&limit=2&tag=api&tag=http"预期结果
{"path":"/search","query":"node js","limit":2,"tags":["api","http"]}searchParams.get('q') 返回第一个匹配值,不存在时返回 null;getAll('tag') 返回所有同名参数,因此更适合标签、筛选条件等允许重复出现的字段。URL 编码的 %20 会在读取查询参数值时还原为空格。
如果请求没有提供 limit,示例会使用字符串默认值 10,再通过 Number() 转为数字。不要直接依赖字符串的真假判断,因为 limit=0、limit=abc 和参数缺失代表的业务含义完全不同。
校验查询参数的类型和范围
查询字符串里的值本质上都是文本,即使客户端发送 limit=20,get('limit') 得到的仍是字符串 "20"。因此接口需要自己完成类型转换和范围判断。本例要求 limit 必须是 1 到 50 的整数。
请求非法参数:
curl -i "http://localhost:3000/search?q=node&limit=200"预期结果应包含 400 Bad Request,响应体为:
{"error":"limit must be an integer from 1 to 50"}这种检查比直接写 Number(value) || 10 更可靠,因为后者会把 0、NaN 等不同输入混在一起。对布尔值、日期和枚举参数也应采用同样思路:先取得原始字符串,再显式转换和验证。
区分路径和查询字符串
url.pathname 只表示路径部分,因此请求 /search?q=node 时得到 /search,不会把查询字符串混入路由判断。查询参数则统一从 url.searchParams 读取,避免手工调用 split('?') 和 split('&')。
手工拆字符串很容易漏掉 %26、%3D、重复键和没有值的参数。标准 URL API 已经处理了这些解析规则,所以实际项目中应先创建 URL 对象,再分别使用 pathname、searchParams.get() 和 searchParams.getAll()。当路径判断、默认值、类型转换和非法输入响应都能通过请求验证时,查询参数解析才算完整。