App Router의 Route Handler(API 라우트)란 무엇인가요?

Question

Accepted Answer

**Route Handler**는 App Router에서 API 엔드포인트를 만드는 방법입니다. Next.js 프로젝트 안에 사는 백엔드 HTTP 핸들러죠. **`route.ts`** 파일로 만들고, HTTP 메서드 이름을 딴 함수를 export합니다.

## 엔드포인트 정의

```ts
// app/api/users/route.ts  →  /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();               // 요청 본문 읽기
  const user = await db.user.create({ data: body });
  return NextResponse.json(user, { status: 201 }); // POST /api/users
}
```

export된 각 메서드(`GET`, `POST`, `PUT`, `PATCH`, `DELETE`)가 해당 메서드를 처리합니다. 표준 Web `Request`/`Response` API(`NextRequest`/`NextResponse`를 통해)를 사용합니다.

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

## Route Handler vs Server Actions/Components를 언제 쓸까

```text
Route Handler를 사용할 때:
  ✓ 모바일 앱 / 외부 클라이언트가 소비하는 공개 API
  ✓ 웹훅(Stripe, GitHub) — URL 엔드포인트가 필요함
  ✓ HTML이 아닌 응답 반환 (JSON, 파일, 이미지, RSS)
  ✓ 클라이언트 측 fetch() 대상

자신의 페이지로 데이터를 읽어 들일 때는 Server Component를,
폼 변경(mutation)에는 Server Action을 선호하세요 — 수동 API 계층을 피합니다.
```

## 그 밖의 기능

```ts
export const runtime = "edge";       // Edge 런타임에서 실행
export const dynamic = "force-dynamic"; // 캐싱 옵트아웃
// 핸들러는 응답 스트리밍, 쿠키 설정, CORS 처리도 가능합니다.
```

## 왜 중요한가

Route Handler는 Next.js를 풀스택으로 만듭니다. 웹 표준 `Request`/`Response`로 프론트엔드와 함께 REST/JSON API, 웹훅, 파일 엔드포인트를 만들 수 있습니다.

언제 이것을(외부 클라이언트, 웹훅, HTML이 아닌 응답) 쓰고 언제 Server Component/Action을(내부 데이터 읽기와 변경) 쓸지를 아는 것이 App Router 백엔드를 깔끔하게 구성하는 비결입니다.