编辑“︁Next.js路由处理程序”︁

{{DISPLAYTITLE:Next.js路由处理程序}}

'''Next.js路由处理程序'''是Next.js框架中用于处理HTTP请求的核心机制，允许开发者在服务器端创建自定义API端点或处理特定路由逻辑。本文将从基础到高级全面解析其工作原理、使用场景及最佳实践。

== 概述 ==
Next.js路由处理程序（Route Handlers）是[[Next.js]] 13.4版本引入的功能，用于替代传统的API Routes（`pages/api`）。它们基于[[Web Request API]]和[[Web Response API]]标准，允许在[[App Router]]结构（`app`目录）下定义服务端逻辑。

=== 核心特性 ===
* '''文件系统路由'''：通过文件路径自动映射HTTP端点
* '''HTTP方法支持'''：直接处理GET、POST、PUT等请求
* '''中间件集成'''：与Next.js中间件无缝协作
* '''流式响应'''：支持动态内容流传输

== 基础用法 ==
路由处理程序需在`app`目录下创建，文件命名约定为`route.js|ts`。

=== 创建基本端点 ===
以下示例展示如何处理GET请求：

<syntaxhighlight lang="javascript">
// app/api/hello/route.ts
export async function GET() {
  return new Response(JSON.stringify({ message: "Hello World" }), {
    headers: { "Content-Type": "application/json" },
  });
}
</syntaxhighlight>

'''输出结果'''：
当访问`/api/hello`时将返回：
<code>
{"message":"Hello World"}
</code>

=== 处理不同HTTP方法 ===
可通过命名导出对应方法处理不同请求类型：

<syntaxhighlight lang="javascript">
// app/api/users/route.ts
export async function GET() {
  // 获取用户列表逻辑
}

export async function POST(request: Request) {
  const body = await request.json();
  // 创建新用户逻辑
}
</syntaxhighlight>

== 高级功能 ==
=== 动态路由参数 ===
使用方括号命名文件可捕获动态路径参数：

<syntaxhighlight lang="javascript">
// app/api/users/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const userId = params.id;
  // 根据ID获取用户
}
</syntaxhighlight>

访问`/api/users/123`时，`params.id`值为"123"。

=== 请求上下文 ===
Next.js提供扩展参数访问路由上下文：

<syntaxhighlight lang="javascript">
export async function GET(
  request: Request,
  {
    params,
    query,
    cookies,
    headers
  }: {
    params: Record<string, string>;
    query: URLSearchParams;
    cookies: Record<string, string>;
    headers: Record<string, string>;
  }
) {
  // 访问各类上下文数据
}
</syntaxhighlight>

=== 响应生成 ===
支持多种响应类型生成方式：

{| class="wikitable"
|-
! 响应类型 !! 示例代码
|-
| JSON响应 | <code>Response.json({ data })</code>
|-
| 重定向 | <code>Response.redirect(new URL('/login', request.url))</code>
|-
| 流式响应 | <code>new Response(ReadableStream)</code>
|}

== 实际应用案例 ==
=== 用户认证端点 ===
实现JWT认证流程：

<syntaxhighlight lang="javascript">
// app/api/auth/login/route.ts
export async function POST(request: Request) {
  const { email, password } = await request.json();
  
  // 验证凭证（模拟）
  if (email === "user@example.com" && password === "secure") {
    const token = "generated.jwt.token";
    return Response.json({ token });
  }
  
  return new Response("Invalid credentials", { status: 401 });
}
</syntaxhighlight>

=== 数据库操作集成 ===
结合Prisma进行数据查询：

<syntaxhighlight lang="javascript">
// app/api/posts/route.ts
import prisma from "@/lib/prisma";

export async function GET() {
  const posts = await prisma.post.findMany();
  return Response.json(posts);
}
</syntaxhighlight>

== 架构原理 ==
<mermaid>
graph TD
    A[HTTP请求] --> B[Next.js路由匹配]
    B --> C{是否匹配路由处理程序?}
    C -->|是| D[执行对应HTTP方法处理函数]
    C -->|否| E[继续其他路由匹配]
    D --> F[生成Response对象]
    F --> G[返回HTTP响应]
</mermaid>

== 性能优化 ==
* 使用<code>export const dynamic = 'force-dynamic'</code>明确声明动态路由
* 对数据密集型操作实现<code>ISR</code>（增量静态再生）
* 利用<code>NextResponse</code>扩展标准响应功能

== 常见问题 ==
=== 与传统API Routes区别 ===
{| class="wikitable"
|-
! 特性 !! 路由处理程序 !! 传统API Routes
|-
| 位置 || <code>app</code>目录 || <code>pages/api</code>
|-
| 文件约定 || <code>route.js</code> || 任意文件名
|-
| 方法处理 || 命名导出 || 通过<code>req.method</code>判断
|}

== 数学表达 ==
路由匹配优先级遵循路径权重计算：
<math>
W = \sum_{i=1}^{n} \begin{cases} 
3 & \text{静态段} \\
2 & \text{动态参数} \\
1 & \text{通配符}
\end{cases}
</math>

== 最佳实践 ==
1. 为敏感路由添加<code>export const runtime = 'edge'</code>提升安全性
2. 使用TypeScript定义请求/响应类型
3. 对公共API实现<code>OPTIONS</code>方法支持CORS
4. 错误处理统一格式：

<syntaxhighlight lang="javascript">
export async function GET() {
  try {
    // 业务逻辑
  } catch (error) {
    return Response.json(
      { error: error.message },
      { status: 500 }
    );
  }
}
</syntaxhighlight>

== 总结 ==
Next.js路由处理程序提供了现代化、类型安全的API开发体验，通过文件系统路由与标准Web API的结合，显著简化了全栈应用的开发流程。开发者应充分利用其模块化特性构建可维护的API层。

[[Category:后端框架]]
[[Category:Next.js]]
[[Category:Next.js路由系统]]