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。路径参数虽然已经匹配路由,也仍需检查格式和权限,不能直接视为可信输入。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

读取路径与查询参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通