Route Handlers (API routes) trong App Router là gì?

Question

Accepted Answer

**Route Handlers** là cách của App Router để xây dựng các endpoint API — các handler HTTP backend sống trong project Next.js của bạn. Bạn tạo chúng bằng một file **`route.ts`**, export các hàm đặt tên theo phương thức HTTP.

## Định nghĩa một endpoint

```ts
// app/api/users/route.ts  →  phục vụ /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();               // đọc body của request
  const user = await db.user.create({ data: body });
  return NextResponse.json(user, { status: 201 }); // POST /api/users
}
```

Mỗi phương thức được export (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) xử lý verb đó. Chúng dùng các API Web `Request`/`Response` chuẩn (qua `NextRequest`/`NextResponse`).

## Đọc params và query

```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);
}
```

## Khi nào dùng Route Handlers so với 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.
```

## Các khả năng khác

```ts
export const runtime = "edge";       // chạy trên Edge runtime
export const dynamic = "force-dynamic"; // không dùng caching
// Handlers cũng có thể stream response, đặt cookie, và xử lý CORS.
```

## Tại sao điều này quan trọng

Route Handlers làm cho Next.js trở thành full-stack: bạn xây dựng các API REST/JSON, webhook và endpoint file cùng với frontend bằng `Request`/`Response` theo chuẩn web.

Biết khi nào nên dùng chúng (client bên ngoài, webhook, response không phải HTML) so với dùng Server Components/Actions (đọc và mutation dữ liệu nội bộ) là then chốt để cấu trúc một backend App Router gọn gàng.