Next.js - API 中间件

Next.js - API 路由辅助函数和请求解析

在使用 Next.js Pages Router 中的 API 路由 时（即 pages/api 目录下的文件），Next.js 在请求（req）对象上提供了一些内置的辅助函数（helpers），以简化解析传入数据等常见任务。

这些辅助函数的作用类似于预配置的中间件（middleware）：

req.cookies：一个包含请求发送的 cookie 的对象。默认为 {}。
req.query：一个包含查询字符串参数的对象。默认为 {}。
req.body：一个包含请求体的对象，根据 Content-Type 头部进行解析。如果头部不存在或请求体无法解析，则默认为 null。例如，application/json 会被解析为一个对象，而 application/x-www-form-urlencoded 也会被解析。

注意：在 App Router 中，你使用 路由处理器（Route Handlers） 代替 API 路由。请求对象（NextRequest）提供了诸如 request.cookies.get('cookieName')、request.nextUrl.searchParams.get('paramName')、await request.json() 或 await request.formData() 之类的方法来访问类似的信息。

我们来创建一个简单的 API 路由示例（Pages Router），演示如何访问查询参数和请求体。

在 pages/api 目录内创建一个名为 user.js 的文件：

export default function handler(req, res) {
  // 访问查询参数（例如：/api/user?id=123）
  const { id } = req.query;

  // 访问请求体（例如用于 POST 或 PUT 请求）
  // 请求体会根据 Content-Type 自动解析
  const requestBody = req.body;

  // 访问请求方法
  const method = req.method;

  if (method === 'GET') {
    // 处理 GET 请求 - 可能是根据 id 获取用户数据
    res.status(200).json({
      message: `Fetching data for user ID: ${id || 'N/A'}`,
      query: req.query
    });
  } else if (method === 'POST') {
    // 处理 POST 请求 - 可能是创建一个新用户
    res.status(201).json({
      message: 'User created successfully!',
      receivedData: requestBody,
      query: req.query // POST 请求中也可以包含查询参数
    });
  } else {
    // 处理其他方法或返回错误
    res.setHeader('Allow', ['GET', 'POST']);
    res.status(405).end(`Method ${method} Not Allowed`);
  }
}

本例演示了如何通过 req.query 访问 URL 参数，通过 req.body 访问请求载荷中发送的数据（例如表单提交或 JSON POST），以及通过 req.method 处理不同的 HTTP 动词（HTTP verbs）。

运行开发服务器

确保你的开发服务器正在运行：

npm run dev

# Example Output:
# ready - started server on 0.0.0.0:3000, url: http://localhost:3000
# event - compiled client and server successfully ...

验证输出

测试带有查询参数的 GET 请求： 打开浏览器并访问 http://localhost:3000/api/user?id=456&source=web。你应该会看到类似以下的 JSON 输出：

{
  "message": "Fetching data for user ID: 456",
  "query": {
    "id": "456",
    "source": "web"
  }
}

测试带有 JSON 请求体的 POST 请求： 你可以使用 curl、Postman 或浏览器内置的 fetch API 等工具发送 POST 请求。在终端中使用 curl 命令：

curl -X POST http://localhost:3000/api/user?ref=test -H "Content-Type: application/json" -d '{"name": "Jane Doe", "email": "jane.doe@example.com"}'

预期的 JSON 响应如下：

{
  "message": "User created successfully!",
  "receivedData": {
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
  },
  "query": {
     "ref": "test"
  }
}

这演示了 Next.js 如何自动解析 JSON 请求体并通过 req.body 提供，同时将查询参数通过 req.query 提供。