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 文件 中:
export async function GET(request: Request) {}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 处理程序。
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 })
}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 将未缓存的数据包含在静态响应中。
静态示例:不访问未缓存的数据或运行时数据,因此将在构建时预渲染:
export async function GET() {
return Response.json({
projectName: 'Next.js',
})
}动态示例:访问非确定性操作。在构建期间,当调用 Math.random() 时预渲染会停止,转为请求时渲染:
export async function GET() {
return Response.json({
randomNumber: Math.random(),
})
}运行时数据示例:访问特定于请求的数据。当调用 headers() 等运行时 API 时,预渲染会终止:
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 对其进行缓存,使其能够包含在预渲染的响应中:
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.js | app/route.js | ✗ 冲突 |
app/page.js | app/api/route.js | ✓ 有效 |
app/[user]/page.js | app/api/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) {}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 参数添加类型:
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期间生成。