React / 系统课时
读取路径与查询参数
读取路径与查询参数
Route Handler 经常需要同时读取资源标识、分页条件和筛选项。本课用一个文章详情接口说明动态路径参数与查询参数的来源、解析方法和校验边界,最终得到可直接调用的 GET 接口。
学习目标
- 区分动态路径参数与 URL 查询参数
- 在 Route Handler 中正确读取并转换参数
- 对缺失值、重复值和非法数字返回稳定响应
区分两类参数
路径参数用于定位资源,例如 /api/posts/post-42 中的 post-42。在 App Router 中,需要把目录命名为 [id],对应文件路径为 app/api/posts/[id]/route.ts。
查询参数位于 ? 之后,通常用于分页、排序或筛选。例如 ?page=2&tag=nextjs&tag=api。它们不会决定命中哪个路由,而是由当前处理函数继续解析。
完成参数解析
当前 Route Handler 的 params 是一个 Promise,需要先 await。查询参数可以从 request.nextUrl.searchParams 读取;单值用 get,重复参数用 getAll。
ts
import type { NextRequest } from "next/server";
type RouteContext = {
params: Promise<{ id: string }>;
};
export async function GET(
request: NextRequest,
context: RouteContext,
) {
const { id } = await context.params;
const pageText = request.nextUrl.searchParams.get("page") ?? "1";
const page = Number(pageText);
const tags = request.nextUrl.searchParams.getAll("tag");
// 分页值必须是正整数,避免把 NaN 继续传给数据库。
if (!Number.isInteger(page) || page < 1) {
return Response.json(
{ code: "INVALID_PAGE", message: "page 必须是正整数", data: null },
{ status: 400 },
);
}
return Response.json({
code: "OK",
message: "查询成功",
data: { id, page, tags },
});
}生效行为:访问动态地址时,id 来自目录段;page 和全部 tag 来自查询字符串。非法分页值会在进入数据库查询前被拒绝。
启动开发服务器后执行,其中 <PORT> 替换为实际端口:
bash
curl "http://localhost:<PORT>/api/posts/post-42?page=2&tag=nextjs&tag=api"预期输出:
json
{"code":"OK","message":"查询成功","data":{"id":"post-42","page":2,"tags":["nextjs","api"]}}处理关键边界
searchParams.get() 在参数不存在时返回 null,不要直接对结果调用字符串方法。数字参数应先转换,再使用 Number.isInteger、范围判断或枚举白名单校验。
同名参数可能出现多次。筛选标签适合用 getAll();只允许单值的参数则应明确选择第一个值,或在发现重复时返回 400。路径参数虽然已经匹配路由,也仍需检查格式和权限,不能直接视为可信输入。
按自己的节奏,确认真正理解。