Next.js Route Handlers

📄 요약

Next.js는 단순한 프론트엔드 라이브러리를 넘어, 백엔드 로직을 직접 품을 수 있는 Route Handlers (구 API Routes) 기능을 제공함. app/api 디렉터리에 route.ts 파일을 생성하는 것만으로 서버리스 API 엔드포인트가 만들어짐.

덕분에 백엔드 서버 없이도 풀스택 개발이 가능하며, 프론트엔드와 백엔드를 한 프로젝트(Monorepo)에서 관리하여 타입 공유, 개발 및 배포 파이프라인 단순화 등 강력한 이점을 제공함.

💡 주요 개념

1. Route Handlers

App Router 환경에서 API 엔드포인트를 생성하는 공식 명칭임. (Pages Router에서는 'API Routes'로 불렸음). app 폴더 내 특정 경로에 route.ts 또는 route.js 파일을 위치시키면 됨. 파일 안에서는 GET, POST, PUT, PATCH, DELETE 등 HTTP 메서드 이름으로 함수를 export하여 요청을 처리함.

2. 파일 기반 라우팅 (File-based Routing)

Next.js의 핵심 원칙으로, 파일 시스템 구조가 URL 주소로 직결됨.

• 정적 (Static): app/api/users/route.ts → /api/users
• 동적 (Dynamic): app/api/users/[id]/route.ts → /api/users/123, /api/users/abc
• 전체 포괄 (Catch-all): app/api/files/[...slug]/route.ts → /api/files/a/b/c

3. 요청(Request)과 응답(Response)

Route Handler 함수는 웹 표준 API인 Request 객체를 첫 번째 인자로 받음. 두 번째 인자로는 동적 라우팅의 파라미터(params) 등을 포함하는 객체를 받을 수 있음.

응답을 보낼 때는 웹 표준 Response 객체나, 편의 기능이 추가된 Next.js의 NextResponse 객체를 사용함. NextResponse.json()은 JSON 응답을, NextResponse.redirect()는 리다이렉션을 쉽게 처리하도록 도와줌.

🧠 코드 예시: 사용자(Users) API

사용자 데이터를 조회, 생성, 수정, 삭제하는 전체적인 API 예시

1. 사용자 목록 조회 및 생성

// 파일 위치: app/api/users/route.ts
import { NextResponse } from 'next/server';

// 데이터베이스 역할을 하는 모의 데이터
let users = [
  { id: 1, name: 'Kim', email: 'kim@example.com' },
  { id: 2, name: 'Bob', email: 'bob@example.com' },
];

/**
 * GET /api/users
 * 모든 사용자 목록을 조회함.
 */
export async function GET() {
  // 실제 앱에서는 DB에서 데이터를 조회하는 로직이 들어감
  return NextResponse.json({ users });
}

/**
 * POST /api/users
 * 새로운 사용자를 생성함.
 */
export async function POST(request: Request) {
  try {
    const { name, email } = await request.json();

    // 간단한 유효성 검사 (실제로는 Zod, Joi 등 라이브러리 사용 권장)
    if (!name || !email) {
      return NextResponse.json(
        { message: 'Name and email are required' },
        { status: 400 } // Bad Request
      );
    }

    const newUser = { id: users.length + 1, name, email };
    users.push(newUser);

    return NextResponse.json(
      { message: 'User created successfully', user: newUser },
      { status: 201 } // Created
    );
  } catch (error) {
    return NextResponse.json(
      { message: 'Invalid request body' },
      { status: 400 }
    );
  }
}

2. 특정 사용자 조회, 수정, 삭제 (동적 라우트)

// 파일 위치: app/api/users/[id]/route.ts
import { NextResponse } from 'next/server';

// 위 파일의 users 배열을 공유한다고 가정함 (실제로는 DB 사용)
let users = [
  { id: 1, name: 'Kim', email: 'kim@example.com' },
  { id: 2, name: 'Bob', email: 'bob@example.com' },
];

/**
 * GET /api/users/[id]
 * 특정 ID의 사용자를 조회함.
 * @param params - { id: string } 형태의 동적 세그먼트
 */
export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const userId = parseInt(params.id, 10);
  const user = users.find((u) => u.id === userId);

  if (!user) {
    return NextResponse.json({ message: 'User not found' }, { status: 404 });
  }

  return NextResponse.json({ user });
}

/**
 * PATCH /api/users/[id]
 * 특정 사용자의 정보를 부분적으로 수정함.
 */
export async function PATCH(
  request: Request,
  { params }: { params: { id: string } }
) {
  const userId = parseInt(params.id, 10);
  const userIndex = users.findIndex((u) => u.id === userId);

  if (userIndex === -1) {
    return NextResponse.json({ message: 'User not found' }, { status: 404 });
  }

  const body = await request.json();
  // 기존 데이터에 새로운 데이터를 덮어씀
  users[userIndex] = { ...users[userIndex], ...body };

  return NextResponse.json({
    message: 'User updated',
    user: users[userIndex],
  });
}

/**
 * DELETE /api/users/[id]
 * 특정 사용자를 삭제함.
 */
export async function DELETE(
  request: Request,
  { params }: { params: { id: string } }
) {
  const userId = parseInt(params.id, 10);
  const initialLength = users.length;
  users = users.filter((u) => u.id !== userId);

  if (users.length === initialLength) {
    return NextResponse.json({ message: 'User not found' }, { status: 404 });
  }

  // 성공적으로 삭제되었지만, 반환할 콘텐츠가 없음
  return new NextResponse(null, { status: 204 });
}

🔍 더 깊이 알아보기

1. Route Segment Config: route.ts 파일에서 export const dynamic = 'force-dynamic' 과 같은 옵션을 설정하여 캐싱 동작을 제어하거나, 엣지(Edge) 환경에서 함수를 실행하도록 지정할 수 있음.
2. 미들웨어 (Middleware): middleware.ts 파일을 사용하여 API 요청이 핸들러에 도달하기 전에 인증(Authentication), 로깅, 리다이렉트 등을 중앙에서 일괄 처리할 수 있음. API 보안과 관리에 필수적임.
3. 에러 핸들링 (Error Handling): try-catch 구문을 적극적으로 사용하여 예상치 못한 오류를 잡고, 일관된 형식의 에러 메시지와 적절한 HTTP 상태 코드를 반환하는 것이 중요함.

https://nextjs-ko.org/docs/app/building-your-application/routing/route-handlers