Next.js App Router 中 API 路由的演进与响应机制解析-js教程-PHP中文网

Next.js App Router 中 API 路由的演进与响应机制解析

Next.js 从 Pages Router 迁移到 App Router 后，API 处理方式发生根本性变化：不再依赖 Express 风格的 req/res 参数，而是采用标准化的 Web API Request/Response 对象，提升可测试性、跨环境兼容性与性能。

next.js 从 pages router 迁移到 app router 后，api 处理方式发生根本性变化：不再依赖 express 风格的 `req/res` 参数，而是采用标准化的 web api `request/response` 对象，提升可测试性、跨环境兼容性与性能。

在 Next.js 的 Pages Router（旧系统）中，API 路由位于 pages/api/xxx.js，其处理函数签名模仿 Node.js HTTP 服务器风格：

// pages/api/code.js
export default async function handler(req, res) {
  res.status(200).json({ message: "successful" });
}

这里 res 是一个 Next.js 封装的响应对象，支持链式调用（如 .status().json()），底层耦合了服务端运行时（如 Node.js Server），不利于单元测试和边缘函数部署。

而在 App Router（新系统）中，API 路由统一放在 app/api/xxx/route.js，必须导出命名的 HTTP 方法处理器（如 GET, POST, PUT 等），且仅接收 Request 对象作为唯一参数——res 参数已被完全移除：

// app/api/code/route.js
export async function POST(request) {
  // ✅ 正确：使用标准 Web Response 构造器
  return new Response(
    JSON.stringify({ message: "successful" }),
    {
      status: 201,
      headers: { "Content-Type": "application/json" },
    }
  );
}

// ❌ 错误：不要传入第二个参数（res），也不应忽略 request
// export const POST = async (req, res) => { ... }

// ❌ 错误：即使只写 req，也仍需返回 Response 实例
// export const GET = async (req) => { console.log("hi"); } // → 返回 undefined，触发 500 错误

这种设计源于对 Web Standards 的原生遵循，使路由处理器成为纯函数：输入是标准 Request，输出必须是 Response。其核心优势包括：

Json Schema Toolkit

使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。

下载

零运行时耦合：不依赖 Express、Node.js 特定 API，天然适配 Vercel Edge Functions、Cloudflare Workers 等边缘环境；
开箱即用的可测试性：可直接用 new Request() 构造请求，调用处理器并断言返回的 Response，无需启动服务器或 mock res；
更小的打包体积与更快启动：避免引入中间件抽象层，减少运行时开销；
深度集成 Next.js 生态：支持 cookies(), headers(), redirect() 等服务端钩子，并与数据缓存（cache: 'no-store'）、流式响应（Streaming SSR）无缝协同。

? 小贴士：

若需解析请求体，请使用 request.json()（JSON）、request.text()（字符串）或 await request.formData()（表单）；
响应头务必显式设置 Content-Type（尤其返回 JSON 时），否则浏览器可能无法正确解析；
不要忘记 return —— 缺失返回值将导致 500 Internal Server Error；
所有方法名必须大写且全为标准 HTTP 方法（GET/POST/DELETE/PATCH/HEAD/OPTIONS），大小写敏感。