路由处理器

路由处理程序

路由处理程序允许您使用 Web 请求和 响应 API 为给定路由创建自定义请求处理程序。

须知：路由处理程序仅在 app 目录中可用。它们等同于 pages 目录中的 API 路由，这意味着您无需同时使用 API 路由和路由处理程序。

约定

路由处理程序在 app 目录中的 route.js|ts 文件中定义

export async function GET(request: Request) {}

路由处理程序可以嵌套在 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 对其进行扩展，为高级用例提供了便捷的辅助功能。

缓存

路由处理程序默认不缓存。但是，您可以选择对 GET 方法进行缓存。其他支持的 HTTP 方法不缓存。要缓存 GET 方法，请在您的路由处理程序文件中使用 路由配置选项，例如 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 })
}

须知：即使在同一文件中与已缓存的 GET 方法一起放置，其他支持的 HTTP 方法也不会被缓存。

特殊路由处理程序

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

路由解析

您可以将 route 视为最低级别的路由原语。

• 它们不参与布局或像 page 一样的客户端导航。
• 在与 page.js 相同的路由中不能存在 route.js 文件。

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

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

阅读更多关于路由处理程序如何 补充您的前端应用程序，或探索路由处理程序 API 参考。

路由上下文助手

在 TypeScript 中，您可以使用全局可用的 RouteContext 助手为路由处理程序中的 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 期间生成。