Next.js Route Handlers 완벽 가이드 — App Router에서 API를 만드는 방법

Next.js Route Handlers 기반 App Router에서 웹 표준 API 엔드포인트 파싱하는 법

App Router의 API 규격을 설계하려면 특정 폴더 아래에 route.ts 파일을 생성해 배치합니다. 단, 해당 경로 폴더 안에 UI 렌더링용 page.tsx 파일이 있으면 빌드 에러가 나니 경로 분할에 신경 써야 합니다. 함수 명칭은 GET, POST, PUT, DELETE 등 HTTP 대문자 메서드명을 그대로 export하며, 입력 인자는 Request 표준 인터페이스를 따릅니다. 따라서 바디 정보를 파싱할 때는 await request.json() 비동기 읽기를 수행해야 하고, 쿼리스트링은 new URL(request.url).searchParams 객체를 개설해 직접 뽑아내야 하는 웹 표준 가이드를 철저히 수행해야 합니다.

// app/api/users/route.ts
import { NextResponse } from 'next/server';
import { prisma } from '@/lib/prisma';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const page = Number(searchParams.get('page') ?? '1');

  const users = await prisma.user.findMany({
    skip: (page - 1) * 20,
    take: 20,
  });
  return NextResponse.json(users);
}

export async function POST(request: Request) {
  const body = await request.json();
  const user = await prisma.user.create({ data: body });
  return NextResponse.json(user, { status: 201 });
}

Next.js Route Handlers 전역 API 보안을 위한 JWT 인증 처리 노하우

로그인 상태를 판독해야 하는 핵심 비즈니스 API 영역은 Authorization 헤더 내의 Bearer JWT 토큰을 떼내어 서명을 검증하는 미들웨어 레이어가 장악해야 합니다. 이를 모든 개별 route.ts 마다 코드 복사 붙여넣기로 때우다간 유지 보수가 지옥이 됩니다. 해결책은 Route Handler를 감싸는 고차 함수(Higher-Order Function) 패턴의 withAuth 유틸리티를 개설하여 검증 단계를 통제하는 것입니다. 혹은 프로젝트 최상단의 middleware.ts 내부에서 특정 /api/* 하위 경로를 매칭 타겟으로 잡아 토큰 가드를 일괄 인젝션해주면, 개별 API 코드에는 오직 핵심 데이터 처리 비즈니스만 담겨 가독성이 기가 막히게 올라갑니다.

Next.js Route Handlers에서 동적 경로 파라미터 매핑 및 force-dynamic 캐시 제어 요령

/api/posts/[id] 형태의 상세 타겟 API를 잡으려면 대괄호 폴더명 전략을 취합니다. 핸들러 함수의 두 번째 인자인 context 속성 내부의 params 비동기 객체를 수령하여 (await params).id 형태로 타겟 ID 값을 안전하게 획득할 수 있죠. 여기서 가장 빈번히 터지는 장애는 GET 메서드 핸들러가 빌드 타임에 단순 static 파일처럼 정적으로 박제되어 실시간 데이터베이스의 변경점을 반영하지 못하고 엣지 캐시만 무한 서빙하는 끔찍한 현상입니다. 실시간 동적 조회가 필수인 API 파일 상단에는 반드시 export const dynamic = 'force-dynamic' 설정을 고정 기입해 주는 습관을 들여야 합니다.