Route Handler와 Server Action, 뭘 언제 써야 할지 헷갈렸던 이유

문제 발생

새로운 데이터 변경 기능을 만드는데, 팀 안에서 Route Handler(app/api/.../route.ts)로 만들지 Server Action("use server" 함수)으로 만들지에 대한 기준이 없어서 매번 임의로 결정하고 있었습니다.

원인 분석

둘 다 서버에서만 실행되는 코드라는 공통점이 있지만, 설계된 목적과 호출 방식이 다릅니다.

• Route Handler: 전통적인 HTTP 엔드포인트입니다. 특정 URL과 HTTP 메서드(GET/POST/...)에 매핑되고, fetch나 외부 클라이언트(모바일 앱, 다른 서비스, webhook 발신자 등)가 표준 HTTP 요청으로 호출할 수 있습니다. 응답 형식(JSON, 파일 등)을 직접 제어합니다.
• Server Action: React의 폼/이벤트 핸들러와 통합되도록 설계된 서버 함수입니다. <form action={myAction}>처럼 폼에 직접 연결하거나, 클라이언트 컴포넌트에서 함수처럼 호출합니다. 내부적으로는 HTTP POST로 동작하지만, 그 세부사항은 프레임워크가 감추고 있어 개발자가 URL이나 요청 형식을 직접 다루지 않습니다.

이 차이 때문에 어느 하나가 항상 우월한 것이 아니라, 누가 이 기능을 호출하는가가 선택의 기준이 됩니다.

해결 방안

1. **폼 제출, 버튼 클릭 등 이 애플리케이션 자신의 UI에서만 호출되는 데이터 변경(mutation)**이라면 Server Action이 적합합니다 — useFormStatus/useActionState 같은 React 훅과 자연스럽게 연동되고, nextCookies처럼 Server Action 전용으로 설계된 라이브러리 기능도 쓸 수 있습니다.

async function createPost(formData: FormData) {
  "use server";
  // ...
}

<form action={createPost}>...</form>

2. 외부 클라이언트가 호출해야 하는 API(webhook 수신, 모바일 앱 백엔드, 다른 서비스와의 연동, 공개 REST API)라면 Route Handler가 맞습니다 — Server Action은 안정적인 공개 URL 계약을 제공하도록 설계되지 않았습니다.
3. GET으로 데이터를 조회만 하는 경우는 애초에 Server Action의 대상이 아닙니다 — Server Action은 뮤테이션(변경) 중심으로 설계됐고, 순수 조회는 서버 컴포넌트에서 직접 데이터 페칭 함수를 호출하는 것이 기본입니다.
4. Sitemap, robots.txt, 이미지 생성처럼 특정 파일 컨벤션으로 정해진 응답을 만들어야 하는 경우도 Route Handler(또는 그 전용 파일 컨벤션)의 영역입니다.
5. 결정이 애매한 경우, "이 기능을 이 프로젝트가 아닌 다른 곳에서도 호출해야 할 가능성이 있는가"를 기준으로 삼으면 대부분 명확해집니다 — 그렇다면 Route Handler, 아니라면 Server Action입니다.

공식 문서

• Next.js Docs: Route Handlers
• Next.js Docs: Server Actions and Mutations