NNext.js 中文网 GitHub

Route Handlers

使用 Web Request 和 Response API,通过 Next.js 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 文件 中:

app/api/route.ts
export async function GET(request: Request) {}
app/api/route.js
export async function GET(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'。

小知识:启用 Cache Components 时不支持 dynamic 导出。有关受支持的方法,请参阅使用 Cache Components 缓存 GET 处理程序。

app/items/route.ts
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 })
}
app/items/route.js
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 方法放在同一个文件中。

使用 Cache Components#

启用 Cache Components 后,GET Route Handlers 遵循与应用程序中普通 UI 路由相同的模型。它们默认在请求时运行,当不访问未缓存或运行时数据时可以预渲染,并且你可以使用 use cache 将未缓存的数据包含在静态响应中。

静态示例:不访问未缓存的数据或运行时数据,因此将在构建时预渲染:

app/api/project-info/route.ts
export async function GET() {
  return Response.json({
    projectName: 'Next.js',
  })
}

动态示例:访问非确定性操作。在构建期间,当调用 Math.random() 时预渲染会停止,转为请求时渲染:

app/api/random-number/route.ts
export async function GET() {
  return Response.json({
    randomNumber: Math.random(),
  })
}

运行时数据示例:访问特定于请求的数据。当调用 headers() 等运行时 API 时,预渲染会终止:

app/api/user-agent/route.ts
import { headers } from 'next/headers'

export async function GET() {
  const headersList = await headers()
  const userAgent = headersList.get('user-agent')

  return Response.json({ userAgent })
}

小知识:如果 GET 处理程序访问网络请求、数据库查询、异步文件系统操作、请求对象属性(如 req.url、request.headers、request.cookies、request.body)、cookies()、headers()、connection() 等运行时 API 或非确定性操作,预渲染就会停止。

缓存示例:访问未缓存的数据(数据库查询),但使用 use cache 对其进行缓存,使其能够包含在预渲染的响应中:

app/api/products/route.ts
import { cacheLife } from 'next/cache'

export async function GET() {
  const products = await getProducts()
  return Response.json(products)
}

async function getProducts() {
  'use cache'
  cacheLife('hours')

  return await db.query('SELECT * FROM products')
}

小知识:use cache 不能直接在 Route Handler 主体内使用;请将其提取到辅助函数中。当新请求到来时,缓存的响应会根据 cacheLife 重新验证。

特殊的 Route Handlers#

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

路由解析#

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

  • 它们不会像 page 那样参与布局或客户端导航。
  • page.js 所在的同一路由上不能存在 route.js 文件。
页面路由结果
app/page.jsapp/route.js✗ 冲突
app/page.jsapp/api/route.js✓ 有效
app/[user]/page.jsapp/api/route.js✓ 有效

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

app/page.ts
export default function Page() {
  return <h1>Hello, Next.js!</h1>
}

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

// 冲突
// `app/route.js`
export async function POST(request) {}

详细了解 Route Handlers 如何补充你的前端应用程序,或浏览 Route Handlers 的 API 参考。

路由上下文辅助工具#

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

app/users/[id]/route.ts
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 期间生成。
Next.js 中文网