Route Handlers

Route Handlers

Route Handlers 允许你使用 Web Request 和 Response API 为给定路由创建自定义请求处理器。

值得注意的是：Route Handlers 仅在 app 目录内可用。它们相当于 pages 目录内的 API Routes，这意味着你不需要同时使用 API Routes 和 Route Handlers。

约定

Route Handlers 在 app 目录内的 route.js|ts 文件中定义：

export async function GET(request: Request) {}

Route Handlers 可以嵌套在 app 目录内的任何位置，类似于 page.js 和 layout.js。但不能在与 page.js 相同的路由段级别上存在 route.js 文件。

支持的 HTTP 方法

支持以下 HTTP 方法：GET、POST、PUT、PATCH、DELETE、HEAD 和 OPTIONS。如果调用了不支持的方法，Next.js 将返回 405 Method Not Allowed 响应。

扩展的 NextRequest 和 NextResponse API

除了支持原生的 Request 和 Response API 外，Next.js 还通过 NextRequest 和 NextResponse 对它们进行了扩展，为高级用例提供便捷的辅助函数。

缓存

Route Handlers 默认不会被缓存。但是，你可以选择对 GET 方法进行缓存。其他支持的 HTTP 方法不会被缓存。要缓存 GET 方法，请在你的 Route Handler 文件中使用路由配置选项，例如 export const dynamic = 'force-static'。

export const dynamic = 'force-static'
 
export async function GET() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY,
    },
  })
  const data = await res.json()
 
  return Response.json({ data })
}

值得注意的是：其他支持的 HTTP 方法不会被缓存，即使它们与被缓存的 GET 方法放在同一个文件中。

特殊的 Route Handlers

特殊的 Route Handlers，如 sitemap.ts、opengraph-image.tsx 和 icon.tsx，以及其他元数据文件，除非它们使用 Dynamic API 或动态配置选项，否则默认保持静态。

路由解析

你可以将 route 视为最底层的路由原语。

• 它们不参与布局或客户端导航，如 page。
• 在与 page.js 相同的路由上不能有 route.js 文件。

每个 route.js 或 page.js 文件接管该路由的所有 HTTP 动词。

export default function Page() {
  return <h1>Hello, Next.js!</h1>
}
 
// 冲突
// `app/route.ts`
export async function POST(request: Request) {}

阅读更多关于 Route Handlers 如何补充你的前端应用程序的信息，或探索 Route Handlers API 参考。

Route Context Helper

在 TypeScript 中，你可以使用全局可用的 RouteContext 辅助函数为 Route Handlers 的 context 参数添加类型：

import type { NextRequest } from 'next/server'
 
export async function GET(_req: NextRequest, ctx: RouteContext<'/users/[id]'>) {
  const { id } = await ctx.params
  return Response.json({ id })
}

值得注意的是

• 类型在 next dev、next build 或 next typegen 期间生成。