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

= Next.js路由处理器 =

== 介绍 ==
Next.js路由处理器（Route Handlers）是Next.js 13.2+引入的功能，允许开发者在应用路由（App Router）架构中创建自定义API端点。这些处理器使用标准Web API（如Request和Response对象）处理HTTP请求，为构建服务端逻辑提供了简洁的方式。

路由处理器的主要特点：
* 替代传统的API路由（`pages/api`）
* 支持动态路由匹配
* 内置支持中间件和类型安全
* 与React Server Components无缝集成

== 基本用法 ==
路由处理器文件必须位于`app/api`目录下，并以`route.ts`（或`route.js`）结尾。以下是简单示例：

<syntaxhighlight lang="typescript">
// app/api/hello/route.ts
import { NextResponse } from 'next/server'

export async function GET() {
  return NextResponse.json({ message: 'Hello World' })
}
</syntaxhighlight>

访问`/api/hello`将返回：
<syntaxhighlight lang="json">
{
  "message": "Hello World"
}
</syntaxhighlight>

== HTTP方法处理 ==
路由处理器支持所有HTTP方法，可以通过命名导出处理不同方法：

<syntaxhighlight lang="typescript">
// app/api/users/route.ts
import { NextResponse } from 'next/server'

export async function GET() {
  // 获取用户列表
  return NextResponse.json([{ id: 1, name: 'John' }])
}

export async function POST(request: Request) {
  const body = await request.json()
  // 创建新用户
  return NextResponse.json({ id: 2, ...body }, { status: 201 })
}
</syntaxhighlight>

== 请求与响应 ==
路由处理器使用Web标准的Request和Response对象，同时提供Next.js增强的`NextResponse`：

=== 访问请求数据 ===
<syntaxhighlight lang="typescript">
// app/api/search/route.ts
import { NextResponse } from 'next/server'

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const query = searchParams.get('q')
  
  return NextResponse.json({ results: await searchDatabase(query) })
}
</syntaxhighlight>

=== 自定义响应 ===
<syntaxhighlight lang="typescript">
// app/api/redirect/route.ts
import { NextResponse } from 'next/server'

export async function GET() {
  return NextResponse.redirect('https://nextjs.org')
}

// 设置Cookie
export async function POST() {
  const response = NextResponse.json({ success: true })
  response.cookies.set('token', 'abc123')
  return response
}
</syntaxhighlight>

== 动态路由 ==
与页面路由类似，可以使用方括号创建动态路由：

<syntaxhighlight lang="typescript">
// app/api/users/[id]/route.ts
import { NextResponse } from 'next/server'

export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const userId = params.id
  return NextResponse.json({ user: await getUserById(userId) })
}
</syntaxhighlight>

== 高级特性 ==

=== 路由分段配置 ===
可以导出`dynamic`和`revalidate`等变量控制路由行为：

<syntaxhighlight lang="typescript">
export const dynamic = 'force-dynamic' // 禁用静态生成
export const revalidate = 60 // 每60秒重新验证
</syntaxhighlight>

=== 流式响应 ===
支持现代Web流式API：

<syntaxhighlight lang="typescript">
// app/api/chat/route.ts
import { createReadableStreamFromReadable } from 'next/dist/compiled/@edge-runtime/primitives/streams'

export async function GET() {
  const encoder = new TextEncoder()
  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 5; i++) {
        controller.enqueue(encoder.encode(`Message ${i}\n`))
        await new Promise(resolve => setTimeout(resolve, 1000))
      }
      controller.close()
    }
  })
  
  return new Response(stream)
}
</syntaxhighlight>

=== 中间件集成 ===
路由处理器可以结合中间件进行身份验证等操作：

<syntaxhighlight lang="typescript">
// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  if (!request.cookies.get('auth')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
}
</syntaxhighlight>

== 实际应用案例 ==

=== 1. 用户认证API ===
<syntaxhighlight lang="typescript">
// app/api/auth/login/route.ts
import { NextResponse } from 'next/server'
import { signJWT } from '@/lib/auth'

export async function POST(request: Request) {
  const { email, password } = await request.json()
  
  if (email === 'user@example.com' && password === 'password') {
    const token = await signJWT({ email })
    const response = NextResponse.json({ success: true })
    response.cookies.set('token', token, { httpOnly: true })
    return response
  }
  
  return NextResponse.json(
    { error: 'Invalid credentials' },
    { status: 401 }
  )
}
</syntaxhighlight>

=== 2. 数据库操作 ===
<syntaxhighlight lang="typescript">
// app/api/products/route.ts
import { NextResponse } from 'next/server'
import { db } from '@/lib/db'

export async function GET() {
  const products = await db.product.findMany()
  return NextResponse.json(products)
}

export async function POST(request: Request) {
  const data = await request.json()
  const product = await db.product.create({ data })
  return NextResponse.json(product, { status: 201 })
}
</syntaxhighlight>

== 性能考虑 ==
路由处理器的性能可以通过以下方式优化：
* 对于不常变化的数据，使用`revalidate`选项
* 对静态数据使用`export const dynamic = 'force-static'`
* 使用Edge Runtime提高响应速度：
  <syntaxhighlight lang="typescript">
  export const runtime = 'edge'
  </syntaxhighlight>

== 与旧版API路由对比 ==
<mermaid>
graph LR
  A[Pages Router] -->|pages/api| B[传统API路由]
  C[App Router] -->|app/api| D[路由处理器]
  D --> E[更好的类型安全]
  D --> F[更简洁的语法]
  D --> G[与RSC更好集成]
</mermaid>

主要改进：
* 更简单的文件结构
* 自动TypeScript类型推断
* 支持流式响应
* 更好的中间件集成

== 常见问题 ==

=== 1. 如何处理CORS ===
<syntaxhighlight lang="typescript">
export async function GET() {
  const response = NextResponse.json({ data: 'value' })
  response.headers.set('Access-Control-Allow-Origin', '*')
  return response
}
</syntaxhighlight>

=== 2. 处理表单提交 ===
<syntaxhighlight lang="typescript">
export async function POST(request: Request) {
  const formData = await request.formData()
  const file = formData.get('file') as File
  // 处理文件上传...
}
</syntaxhighlight>

== 数学公式示例 ==
在处理数据分析API时，可能会用到数学公式。例如计算平均值：

<math>
\bar{x} = \frac{1}{n}\sum_{i=1}^{n} x_i
</math>

== 总结 ==
Next.js路由处理器提供了现代化、类型安全的方式来构建API端点，具有以下优势：
* 简洁的基于文件的路由系统
* 与App Router深度集成
* 支持所有HTTP方法
* 提供Web标准API的扩展功能
* 适合从简单到复杂的各种用例

通过合理使用路由处理器，开发者可以构建高效、可维护的后端API，同时保持前后端代码的紧密集成。

[[Category:后端框架]]
[[Category:Next.js]]
[[Category:Next.js数据获取]]