Next.js App Router 中 API 路由的演进与实践指南-js教程-PHP中文网

Next.js App Router 中 API 路由的演进与实践指南

Next.js 13+ 的 App Router 引入了基于 Response 对象的全新 API 路由范式，取代了 Pages Router 中基于 req/res 的 Express 风格处理方式，提升了可测试性、跨环境兼容性与框架集成度。

next.js 13+ 的 app router 引入了基于 `response` 对象的全新 api 路由范式，取代了 pages router 中基于 `req/res` 的 express 风格处理方式，提升了可测试性、跨环境兼容性与框架集成度。

在 Next.js 的演进过程中，API 路由的实现方式发生了根本性变化——从 Pages Router 的 Node.js 服务器依赖模式，转向 App Router 的标准化 Web API 模式。这一转变不仅体现为语法差异，更反映了 Next.js 向边缘运行时（Edge Runtime）、服务端组件（Server Components）和统一数据流架构的深度演进。

✅ 核心差异：从 `req/res` 到 `Request/Response`

Pages Router（旧）：
使用 pages/api/xxx.js，导出 handler(req, res)，依赖 Node.js 的 http.ServerResponse（如 res.status(200).json(...)）。该模式紧密耦合于 Node.js 环境，难以在非 Node 环境（如 Vercel Edge Functions、Deno、Cloudflare Workers）中运行或单元测试。
```
// pages/api/code.js
export default async function handler(req, res) {
  res.status(200).json({ message: "successful" });
}
```
App Router（新）：
使用 app/api/xxx/route.js，按 HTTP 方法导出命名函数（如 GET, POST），仅接收 Request 对象（无 res 参数），必须显式返回 Response 实例：
```
// app/api/code/route.js
export async function POST(request) {
  const body = await request.json();
  return Response.json(
    { message: "successful" },
    { status: 201 }
  );
}
```

✅ 推荐使用 Response.json() 辅助方法（自动设置 Content-Type: application/json 和序列化），而非手动 new Response(JSON.stringify(...), {...}) —— 更安全、简洁、语义清晰。

? 为什么弃用 `res`？设计哲学解析

环境无关性（Environment Agnosticism）：
Response 是 Web 标准（WHATWG 规范）的一部分，被所有现代运行时（Node.js、Vercel Edge、Cloudflare Workers、Deno）原生支持；而 res.end() 等方法是 Node.js 特有的。这使得同一段路由代码可在不同部署目标无缝运行。
可测试性跃升：
你可直接构造 new Request('http://localhost/api/code', { method: 'POST', body: JSON.stringify({...}) }) 并调用 POST(request)，断言返回的 Response 实例，无需启动 HTTP 服务器或 mock res 对象。
与 React Server Components 深度协同：
App Router 的整个数据获取层（fetch、async Server Components、generateStaticParams）均基于 Promise 和标准 Web API，统一的数据流模型降低了心智负担与错误边界。

⚠️ 注意事项与最佳实践

❌ 错误写法（res 参数无效且被忽略）：

export const GET = async (req, res) => { /* res is unused! */ } // 不报错但无意义

✅ 正确签名（仅 request）：

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

下载
```
export async function GET(request) { ... }
export async function POST(request) { ... }
```

✅ 支持中间件式逻辑（如鉴权、日志）：

export async function POST(request) {
  const authHeader = request.headers.get('Authorization');
  if (!authHeader) return Response.json({ error: 'Unauthorized' }, { status: 401 });

  const data = await request.json();
  return Response.json({ success: true, received: data });
}

✅ 自动 Content-Type 处理（推荐）：

// ✅ 自动设置 headers + JSON stringify
return Response.json({ message: "ok" }, { status: 200 });

// ❌ 手动处理易出错（如忘记 header）
return new Response(JSON.stringify({ message: "ok" }), {
  status: 200,
  headers: { 'Content-Type': 'application/json' }
});

? 总结

Next.js App Router 的 API 路由不是简单的语法糖升级，而是面向未来部署场景（边缘计算、全栈 Server Components）的架构重构。它以标准 Request/Response 为核心，解耦运行时依赖，提升可移植性与可维护性。迁移时请牢记：没有 res，只有 return Response；没有隐式响应，只有显式、可组合、可测试的 Web 响应对象。