Next.js - API 路由

Next.js - 使用路由处理程序 (Route Handlers) 构建 API 路由

Next.js 允许您使用 路由处理程序 (Route Handlers) 直接在项目中构建后端 API 端点。这些处理程序是定义在 app 目录（通常在 app/api/ 子目录下）中的 route.ts（或 route.js）文件中的函数。

每个 route.ts 文件可以导出对应于 HTTP 方法（例如 GET、POST、PUT、DELETE）的函数。这些函数接收一个 Request 对象，并应返回一个 Response 对象（通常使用 NextResponse 辅助函数）。

app/api/hello/route.ts 映射到 /api/hello 端点。
app/api/users/[userId]/route.ts 映射到动态端点，例如 /api/users/123。

创建一个简单的 API 端点

让我们创建一个返回简单 JSON 消息的基本 API 端点。

创建目录结构：app/api/greeting/。
在 app/api/greeting/ 目录内，创建一个名为 route.ts 的文件，内容如下：

import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  // 您可以从 request 对象访问查询参数
  const searchParams = request.nextUrl.searchParams;
  const name = searchParams.get('name') || 'World'; // 默认值是 'World'

  const responseData = {
    message: `Hello, ${name}! Welcome to the Next.js API.`
  };

  // 使用 NextResponse 辅助函数返回 JSON 响应
  return NextResponse.json(responseData);
}

这段代码定义了一个异步函数 GET，用于处理发送到 /api/greeting 的 GET 请求。它读取一个可选的 name 查询参数，并返回一个个性化的 JSON 问候消息。

关键概念

**文件约定：**API 端点由 route.ts 或 route.js 文件定义。
**HTTP 方法：**导出与 HTTP 动词（GET、POST、PATCH、DELETE 等）匹配的命名函数。
**Request 对象：**函数接收一个 Request 对象（标准的 Web API），该对象可能被 NextRequest 扩展以提供 Next.js 特有的辅助功能，如 nextUrl。
**Response 对象：**函数必须返回一个 Response 对象（标准的 Web API）。来自 next/server 的 NextResponse 辅助函数提供了便捷的方法，如 NextResponse.json()。

启动开发服务器

如果开发服务器未运行，请启动它：

npm run dev

验证输出

在浏览器中打开 http://localhost:3000/api/greeting。您应该看到：

{"message":"Hello, World! Welcome to the Next.js API."}

现在尝试添加一个查询参数：http://localhost:3000/api/greeting?name=Alice。您应该看到：

{"message":"Hello, Alice! Welcome to the Next.js API."}

路由处理程序 (Route Handlers) 提供了一种强大的方式，作为 Next.js 应用的一部分构建无服务器 API 函数，适用于处理表单提交、与数据库交互或集成第三方服务等任务。