Frontend Academy · 강의

Next.js API 경로와 미들웨어

api/ 디렉터리에 서버리스 API 엔드포인트를 만들고, Route Handler에서 요청을 처리하며, 인증과 리디렉션을 위해 엣지 미들웨어를 실행합니다.

Next.js API 경로와 미들웨어은(는) CoddyKit의 무료 Frontend Academy 강의입니다. 이것은 4개 중 4번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 Frontend Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. Frontend Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

API 라우트가 필요한 이유

Next.js는 앱과 함께 서버를 번들링하므로, 별도의 Node 프로젝트 없이 페이지와 나란히 백엔드 엔드포인트를 작성할 수 있습니다. 프록시, 폼 제출, 웹훅, 소규모 API에 적합합니다.

페이지 라우터 API 라우트

pages/api/의 파일은 Express 방식의 (req, res)를 사용하는 기본 함수를 내보냅니다.

// pages/api/users.ts
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'GET') {
    const users = await db.users.findMany();
    return res.json(users);
  }
  if (req.method === 'POST') {
    const user = await db.users.create({ data: req.body });
    return res.status(201).json(user);
  }
  return res.status(405).end();
}

앱 라우터 라우트 처리기

앱 라우터는 웹 표준 요청/응답 API를 사용합니다. 각 HTTP 메서드는 이름이 지정된 내보내기입니다.

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

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

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

동적 API 라우트

동적 세그먼트도 같은 방식으로 작동합니다. app/api/users/[id]/route.ts는 /api/users/123과 일치합니다.

// app/api/users/[id]/route.ts
export async function GET(req: Request, { params }: { params: { id: string }}) {
  const user = await db.users.findUnique({ where: { id: params.id }});
  if (!user) return new Response('Not Found', { status: 404 });
  return Response.json(user);
}

쿠키와 헤더 읽기

앱 라우터에서는 next/headers의 도우미를 사용하십시오. 이 도우미는 요청 범위로 동작합니다.

import { cookies, headers } from 'next/headers';

export async function GET() {
  const token = cookies().get('token')?.value;
  const userAgent = headers().get('user-agent');
  // ...
}

응답 스트리밍

라우트 처리기는 스트리밍 응답을 반환할 수 있어 AI 채팅 완성이나 대용량 파일 생성에 유용합니다.

export async function GET() {
  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 5; i++) {
        controller.enqueue(encoder.encode(`chunk ${i}\n`));
        await new Promise(r => setTimeout(r, 500));
      }
      controller.close();
    }
  });
  return new Response(stream);
}

미들웨어 — 라우트보다 먼저 실행

프로젝트 루트의 middleware.ts는 요청이 페이지나 API 라우트에 도달하기 전에 실행됩니다. 인증 확인, 리디렉션, 헤더 재작성, A/B 실험에 사용하십시오.

// middleware.ts
import { NextResponse, type NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('token');
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  return NextResponse.next();
}

미들웨어 매칭

매칭 설정을 사용해 미들웨어가 실행되는 경로를 제한하십시오.

export const config = {
  matcher: [
    '/dashboard/:path*',
    '/api/:path*',
    '/((?!_next/static|_next/image|favicon.ico).*)'
  ]
};

미들웨어 런타임

미들웨어는 기본적으로 Edge Runtime에서 실행됩니다. 이는 가벼운 V8 격리 환경이며 전체 Node 환경이 아닙니다. 사용할 수 있는 API가 제한되어 있어 fs 같은 Node 모듈이나 네이티브 종속 항목을 사용할 수 없습니다.

미들웨어를 사용한 인증 패턴

일반적인 방식은 미들웨어에서 JWT를 verify하고, 없거나 유효하지 않으면 로그인으로 리디렉션하며, 후속 라우트가 읽을 수 있는 요청 헤더에 decoded 사용자 정보를 첨부하는 것입니다.

import jwt from 'jsonwebtoken';

export function middleware(req: NextRequest) {
  const token = req.cookies.get('token')?.value;
  if (!token) return NextResponse.redirect(new URL('/login', req.url));
  try {
    const decoded = jwt.verify(token, process.env.SECRET!);
    const res = NextResponse.next();
    res.headers.set('x-user-id', String(decoded.sub));
    return res;
  } catch {
    return NextResponse.redirect(new URL('/login', req.url));
  }
}

미들웨어에서 요청 속도 제한하기

미들웨어와 KV 저장소(Upstash, Vercel KV)를 결합하면 API 로직에 도달하기 전에 IP별 요청 속도 제한을 적용할 수 있습니다.

API 라우트를 사용하지 말아야 할 때(NOT)

별도의 마이크로서비스나 공유 API가 필요하다면 실제 백엔드를 배포하십시오(Hono, Express, NestJS). Next.js API 라우트는 프록시, 웹훅, 앱별 엔드포인트에 적합하지만 다른 클라이언트에 공개 API를 제공하는 용도에는 적합하지 않습니다.

빠른 확인

Next.js 미들웨어는 어디에서 실행되며, 가장 일반적인 사용 사례는 무엇입니까?

복습: API 라우트와 미들웨어

페이지 라우터: pages/api에서 req/res를 사용합니다. 앱 라우터: Request/Response를 사용하는 메서드 내보내기(GET/POST 등)를 포함한 app/api/.../route.ts를 사용합니다. next/headers를 통해 쿠키와 헤더를 읽습니다. ReadableStream으로 응답을 스트리밍할 수 있습니다. middleware.ts는 라우트보다 먼저 Edge에서 실행되며 인증, 리디렉션, 헤더 처리를 담당합니다. 매처 설정으로 경로를 제한합니다. 공개 API에는 실제 백엔드를 사용하십시오.

자주 묻는 질문

“Next.js API 경로와 미들웨어” 강의는 무료인가요?

네 — “Next.js API 경로와 미들웨어” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 Frontend Academy 강의 전체를 잠금 해제할 수 있습니다. Frontend Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

“Next.js API 경로와 미들웨어”에서 뭘 배우나요?

api/ 디렉터리에 서버리스 API 엔드포인트를 만들고, Route Handler에서 요청을 처리하며, 인증과 리디렉션을 위해 엣지 미들웨어를 실행합니다. 브라우저에서 직접 실행하는 실습 코드로 Frontend Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

Frontend Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 Frontend Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 4번째 강의입니다.

“Next.js API 경로와 미들웨어” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 Frontend Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 Frontend Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← Frontend Academy(으)로 돌아가기