App Router 中的路由处理器（API 路由）是什么？

Question

Accepted Answer

**Route Handlers** 是 App Router 构建 API 端点的方式——后端 HTTP 处理程序位于你的 Next.js 项目中。你通过创建 **`route.ts`** 文件来定义它们，导出以 HTTP 方法命名的函数。

## 定义端点

```ts
// app/api/users/route.ts  →  serves /api/users
import { NextRequest, NextResponse } from "next/server";

export async function GET() {
  const users = await db.user.findMany();
  return NextResponse.json(users);             // GET /api/users
}

export async function POST(req: NextRequest) {
  const body = await req.json();               // read the request body
  const user = await db.user.create({ data: body });
  return NextResponse.json(user, { status: 201 }); // POST /api/users
}
```

每个导出的方法（`GET`、`POST`、`PUT`、`PATCH`、`DELETE`）处理对应的 HTTP 动词。它们使用标准的 Web `Request`/`Response` API（通过 `NextRequest`/`NextResponse`）。

## 读取参数和查询

```ts
// app/api/users/[id]/route.ts → /api/users/123
export async function GET(req: NextRequest, { params }: { params: { id: string } }) {
  const url = new URL(req.url);
  const sort = url.searchParams.get("sort"); // ?sort=name
  const user = await db.user.findUnique({ where: { id: params.id } });
  return NextResponse.json(user);
}
```

## 何时使用 Route Handlers 与 Server Actions/Components

```text
Use Route Handlers for:
  ✓ Public APIs consumed by mobile apps / external clients
  ✓ Webhooks (Stripe, GitHub) — they need a URL endpoint
  ✓ Returning non-HTML (JSON, files, images, RSS)
  ✓ Client-side fetch() targets

Prefer Server Components for reading data into your own pages,
and Server Actions for form mutations — they avoid a manual API layer.
```

## 其他功能

```ts
export const runtime = "edge";       // run on the Edge runtime
export const dynamic = "force-dynamic"; // opt out of caching
// Handlers can also stream responses, set cookies, and handle CORS.
```

## 为什么这很重要

Route Handlers 让 Next.js 成为全栈框架：你可以使用 web 标准的 `Request`/`Response` 在前端旁边构建 REST/JSON API、webhook 和文件端点。

了解何时使用它们（外部客户端、webhook、非 HTML 响应）与使用 Server Components/Actions（内部数据读取和变更）的区别，是保持 App Router 后端结构清晰的关键。