路由处理器
Route Handlers(路由处理器) 允许你使用 Web Request 和 Web Response API 为一个特定的路由创建自定义请求处理程序.
请注意: Route Handlers(路由处理器) 只能在
app
目录内允许被使用. 它和pages
目录内的 API Routes(API 路由) 是同一个东西, 所以你不需要同时使 用 API Routes(API 路由) 和 Route Handler(路由处理器).
Convention (文件名协定)
通过在 app
目录内定义 route.js|ts
文件来使用 Route Handlers(路由处理器).
export async function GET(request: Request) {}
Route Handlers(路由处理器) 可以在 app
目录下嵌套, 与 page.js
和 layout.js
相似. 但 route.js
文件不能存在于与 page.js
同一路由段层级的文件夹中.
Supported HTTP Methods (支持的 HTTP 方法)
以下 HTTP methods(Http 方法) 是被支持的: GET
, POST
, PUT
, PATCH
, DELETE
, HEAD
, OPTIONS
. 如果被一个不支持的方法调用, Next.js 会返回 405 Method Not Allowed
返回.
Extended NextRequest
and NextResponse
APIs (被扩展的 NextRequest
和 NextResponse
API)
除了支持原生的 Request 和 Response 外, Next.js 还扩展了它们, 变为了 NextRequest 和 NextResponse, 以提高对高级用例的便利使用.
Behavior (行为)
Caching (缓存)
默认情况下, 使用 GET
方法请求 Route Handlers(路由处理器) 时, 其 Response
对象会被缓存.
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 });
}
Typescript 警告:
Response.json()
从 Typescript 5.2 后开始才能使用. 如果你使用了更低版本的 Typescript, 你可以使用NextResponse.json()
来定义响应.
Opting out of caching (退出缓存)
你可以使用以下方式来不使用缓存:
- 在
GET
方法内使用Request
对象. - 使用其他 HTTP 方法.
- 使用 Dynamic Functions(动态函数), 像
cookies
和headers
. - 通过Segment Config Options(段配置选项) 手动指定动态模式.
比如:
export async function GET(request: Request) {
const { searchParams } = new URL(request.url);
const id = searchParams.get("id");
const res = await fetch(`https://data.mongodb-api.com/product/${id}`, {
headers: {
"Content-Type": "application/json",
"API-Key": process.env.DATA_API_KEY,
},
});
const product = await res.json();
return Response.json({ product });
}
又比如, POST
方法会导致该路由处理器被认为是动态的.
export async function POST() {
const res = await fetch("https://data.mongodb-api.com/...", {
method: "POST",
headers: {
"Content-Type": "application/json",
"API-Key": process.env.DATA_API_KEY,
},
body: JSON.stringify({ time: new Date().toISOString() }),
});
const data = await res.json();
return Response.json(data);
}
请注意: 与 API Routes(API 路由) 一样, 路由处理器也可用于处理表单提交等情况. 我们正在开发一种与 React 深度结合的, 用于handling forms and mutations(处理表单和突变)的新抽象.
Route Resolution (路由解析)
你可以认为一个 route(路由)
是最底层级的原始路由.
- 它们不会像
page
一样参与到 layouts(布局) 和 client-side navigations(客户端导航). - 在
page.js
的目录下不能有route.js
.
Page(页面) | Route(路由) | Result(结果) |
---|---|---|
app/page.js | app/route.js | Conflict |
app/page.js | app/api/route.js | Valid |
app/[user]/page.js | app/api/route.js | Valid |
任一 route.js
或 page.js
文件都会接管该路由的所有 HTTP 动作.
export default function Page() {
return <h1>Hello, Next.js!</h1>;
}
// ❌ Conflict
// `app/route.js`
export async function POST(request) {}
Examples (示例)
以下示例将会向你展示怎么将 Route Handlers(路由处理器) 与其他 Next.js API 和 Next.js 功能相结合.
Revalidating Cached Data (重新验证缓存数据)
你可以使用 next.revalidate
选项来 revalidate cached data (重新验证缓存数据):
export async function GET() {
const res = await fetch("https://data.mongodb-api.com/...", {
next: { revalidate: 60 }, // Revalidate every 60 seconds
});
const data = await res.json();
return Response.json(data);
}
备选的, 你可以使用 revalidate
Segment config option(段控制选项):
export const revalidate = 60;