🚀 Next.js 심화 4장: Server Actions — API 라우트 없는 세상의 혁명

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 비유로 먼저 이해하기
• 🧩 Server Actions의 탄생: use server의 진짜 의미 🟢
• 🌱 클라이언트 컴포넌트와의 결합: 폼 너머의 함수 호출 🟡
• 🛡️ useActionState와 낙관적 UI(Optimistic UX) 설계 🔴
• 💥 에러 해결 카탈로그
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분 (전체) / 핵심 파트만: 8분

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 영철(신입): "게시글 작성 폼 다 만들었어요! 근데, 이걸 DB에 저장하려면 또 app/api/posts/route.ts 파일 만들어서 POST 메소드 짜고, 클라이언트 쪽에선 fetch로 URL 하드코딩해서 보내고, 상태 관리 코드 수십 줄 짜고... 기능 구현보다 API 세팅하는 데 시간이 더 드네요. 언제 이 짓을 다 하죠?"
• 영호(리드): "영철 님... 언제 적 app/api를 쓰고 계신 겁니까! '서버 액션(Server Actions)' 을 쓰면 프론트 함수 찰흙 빚듯이 그냥 function 하나 선언해놓고, 클라이언트 컴포넌트 버튼에서 그걸 직접 import해서 냅다 누르면 끝나요! Next.js가 뒤에서 남몰래 API 텍스트 통신 구멍을 다 파준다고요!"

🗺️ 이 문서의 흐름
API 라우트의 종말 → use server 선언법 → 클라이언트 연동 → 심화 3장의 캐시 무효화와의 결합

🎯 이 문서를 다 읽으면 할 수 있는 것

• 불필요하게 늘어나는 app/api 폴더의 RESTful 엔드포인트 파일들을 전부 삭제하고, 깔끔한 .ts 파일 내의 서버 함수 모음집으로 리팩토링할 수 있다.
• 자바스크립트가 로딩되기 전이거나 브라우저에서 JS가 꺼져(Disable)있는 환경에서도, 낡은 브라우저 폼 네이티브 동작만으로 서버에 데이터를 저장시키는 마법을 경험한다.

🤔 왜 알아야 하는가

과거 React에서 데이터를 서버(DB)로 던져서 생성/수정/삭제(Mutation) 하는 흐름은 지극히 뻔하고 또 고통스러웠어.

1. onSubmit 핸들러 연결
2. e.preventDefault() 로 브라우저 깜빡임 막기
3. 화면에 보여줄 loading 상태 변수 true 켜기
4. fetch('/api/...') 로 통신
5. 성공하면 loading 끄고, 실패하면 에러 state 세팅하고...
6. 데이터를 받은 백엔드는 또 껍데기 API 깎아서 DB에 인서트하고...

Vercel 천재들은 이걸 보고 생각했어.
"어차피 요즘 클라이언트도 JavaScript고, 백엔드 서버 엔진(Next.js)도 JavaScript인데 도대체 왜 가운데에 API라는 거대한 텍스트 변환 장벽(Endpoint)을 무리하게 두고 고통 받아야 하지? 둘을 하나인 것처럼 찰싹 붙여버리면 안 될까?"

이 과감한 발상에서 탄생한 것이 바로 넥스트의 가장 위대한 발명품 중 하나인 Server Actions 야. 마치 프론트 개발자가 클라이언트 코드 내부 코딩 방식 그대로 서버 DB를 직접 주물럭거리는 듯한 압도적 DX(개발자 경험)를 선사하는 이 기능을 모르면 시니어가 될 수 없어.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면? (영수네 마법 편지)

❌ 과거 (영철이의 팩스 통신)
집에 있는 영철이가 유치원(서버) 조립 박스를 돌리려면,
팩스 번호(API 엔드포인트 URL)를 찾아서, 편지 양식(JSON 포맷)에 맞춰 글씨를 정자로 쓰고, 송신 버튼 누르고, 제대로 전송됐는지 응답 용지 돌아올 때까지 계속 옆에서 기다려야 했어.

✅ 현재 (Server Actions - 영호의 공유 컨텍스트 버튼)
그냥 영철이 방 리모컨에 "유치원 박스 조립해줘" 버튼이 생겼어.
영철이가 방에서 그 버튼을 쑥 누르면, 유치원(서버)에 있는 마법 상자가 알아서 전원을 켜고 조립을 완료해. 영철이는 팩스 번호나 JSON 양식 따윈 몰라도 돼. 텍스트 변환은 공유 컨텍스트(Next.js 자동 암호화 통신)가 전부 알아서 처리해주거든!

🧩 Server Actions의 탄생: use server의 진짜 의미 🟢

use client의 반대말이 use server 일까?
아니야. 서버 컴포넌트는 아무 지시자가 없는 '기본값(default)'일 뿐이야.
use server 의 진짜 의미는 "서버 액션(클라이언트가 원격으로 찌를 수 있는 마법의 서버 함수)을 선언하겠다" 는 무서운 선언문이야.

상황: DB에 게시글 저장하기

// app/actions/post.ts (💡 오로지 서버 로직만 담긴 순수 파일)
'use server' // 🌟 이 파일 안의 모든 함수는 브라우저(클라이언트)가 원격으로 호출(RPC) 할 수 있다!
 
import db from '@/lib/db'
import { revalidatePath } from 'next/cache' // 심화 3장에서 배운 도끼
 
// 놀랍게도 이 함수는 API 엔드포인트 URL이 없다. 그냥 함수다!
export async function createPost(formData: FormData) {
  const title = formData.get('title') as string;
  const content = formData.get('content') as string;
 
  // 브라우저 쪽에선 절대 모르는 완벽한 백엔드 보안 구간 (DB Insert)
  await db.post.create({ data: { title, content } });
 
  // 성공 시, 캐시를 무효화해 화면을 갱신!
  revalidatePath('/posts');
}

이걸로 백엔드 코드 생성은 끝 이야. app/api/... 폴더 파고, NextResponse.json 리턴해주고 할 필요가 아예 사라졌어!

🌱 클라이언트 컴포넌트와의 결합: 폼 너머의 함수 호출 🟡

자, 이제 저 마법의 서버 함수를 컴포넌트 쪽에서 그냥 불러다 쓰기만 하면 돼. 놀라운 점은 서버 기반 <form> 과, 클라이언트 컴포넌트의 onClick 버튼 양쪽 모두에서 너무나 쉽게 동작한다는 거야.

1) 자바스크립트를 쓰지 않는 순정 Form 동작 (Progressive Enhancement)

클라이언트 컴포넌트로 만들 구차한 이유가 없다면, 그냥 서버 컴포넌트로 작성해도 다 돌아가!

// app/posts/new/page.tsx (서버 컴포넌트 유지!)
import { createPost } from '@/app/actions/post' // 방금 만든 그 서버 함수를 그대로 수입!
 
export default function NewPostPage() {
  return (
    // 🌟 form의 'action' 속성에 그저 "서버 함수 자체"를 끼워 넣기만 하면 끝!
    <form action={createPost}>
      <input type="text" name="title" />
      <textarea name="content" />
      <button type="submit">저장하기</button>
    </form>
  )
}

이게 왜 혁명적인가?
브라우저 환경에서 유저가 "저장하기"를 누르면, 브라우저의 순정(Native) 폼 전송 방식이 발동해. JavaScript 코드가 다운로드되기 전이든, JS 자체가 차단된 보안 환경이든 프레임워크가 쌩 브라우저 Form Action을 낚아채서 안전하게 서버를 쳐줘. e.preventDefault 가 그립지 않은 시원한 쾌감!

2) 클라이언트 컴포넌트(use client) 내부에서 마음껏 호출하기

당연히 "어 난 폼 태그 쓰기 싫고 그냥 onClick 으로 좋아요 숫자 올리고 싶은데?" 도 100% 지원돼.

// app/components/LikeButton.tsx
'use client'
 
import { addLike } from '@/app/actions/post' // 서버 엑션을 수입!
import { useTransition } from 'react'
 
export default function LikeButton({ postId }) {
  const [isPending, startTransition] = useTransition();
 
  const handleLike = () => {
    // startTransition으로 감싸면 백그라운드 서버 요청 중에도 에러/로딩 UI를 안 끊기게 제어 가능!
    startTransition(async () => {
      await addLike(postId); // fetch? API 라우트? 그딴 거 없다. 그냥 비동기 서버함수 냅다 호출!
    });
  }
 
  return (
    <button onClick={handleLike} disabled={isPending}>
      {isPending ? '처리중...' : '❤️ 좋아요'}
    </button>
  )
}

Next.js 컴파일러가 빌드할 때 저 addLike(postId) 부분의 문맥을 분석해서, 브라우저가 읽을 때 몰래 랜덤 API 주소(예: POST /_next/server-action)로 치환되는 코드로 암호화(RPC) 포장해버리는 마술을 부리는 거야. 프론트는 "그냥 서버 함수를 실행했을 뿐!" 이지.

🛡️ useActionState와 낙관적 UI(Optimistic UX) 설계 🔴

시니어급 프론트엔드가 고민하는 가장 큰 폼 전송의 두 가지 벽이 있어.

1. 회원가입 제출 후 "비밀번호 길이가 짧습니다" 같은 서버 유효성 검사 반환 에러 값 을 화면에 어떻게 뿌리지?
2. 좋아요 버튼을 누르는 순간 바로 서버가 처리하기도 전에 화면엔 '하트 뿅!' 하고 선반영(Optimistic Update)되어서 빨라 보이게 어떻게 하지?

시니어의 무기: useActionState (React 19 최신 훅)

기존 useFormState 가 진화한 끝판왕 훅이야.
서버 액션 함수의 "로딩 여부(isPending)" 와 "결괏값 도출(State)" 을 완벽히 연결해주는 다리 역할을 해.

// app/actions/auth.ts
'use server'
 
export async function loginAction(prevState: any, formData: FormData) {
  const email = formData.get('email');
 
  if (!email.includes('@')) {
    // 🌟 성공/실패 여부를 자유자재로 리턴 객체로 내뱉는다!
    return { error: '이메일 형식이 아닙니다!', success: false };
  }
 
  await db.login();
  return { error: null, success: true };
}

// app/Login.tsx
'use client'
import { useActionState } from 'react'
import { loginAction } from './actions/auth'
 
export default function LoginForm() {
  // 🌟 마법의 3박자: [현재서버응답상태, 폼에연결할발사함수, 백그라운드로딩여부]
  const [state, formAction, isPending] = useActionState(loginAction, { error: null });
 
  return (
    <form action={formAction}>
      <input type="text" name="email" />
      <button disabled={isPending}>로그인</button>
 
      {/* 🌟 서버에서 돌아온 에러가 있다면 즉시 화면에 노출 (SPA 경험 완벽 유지!) */}
      {state.error && <p className="text-red-500">{state.error}</p>}
    </form>
  )
}

😎 낙관적 업데이트(useOptimistic)와의 조합
페이스북 좋아요 버튼처럼, 서버 응답이 오기 전까지 컴포넌트 UI상에서만 가짜로 +1 올린 상태를 보여주다가, 서버 액션이 에러 나면 다시 스르륵 -1 로 원상 복구시키는 마법의 useOptimistic() 훅을 이 액션들과 결합하면 프론트의 UX는 현존 최고봉 단계로 올라서게 된다.

💥 에러 해결 카탈로그

에러 메시지가 뜨면 Ctrl+F로 검색해봐.

❌ Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with "use server"

원인: 무심코 데이터를 조작하는 일반 서버용 유틸 함수를 브라우저 컴포넌트 버튼 onClick 에다 프롭스처럼 넘겨주려 했음. 함수 껍데기 자체는 클라이언트로 전송이 불가능하다.
해결책: 그 함수 상단(혹은 파일 최상단)에 'use server' 부적을 붙여서 이 함수가 RPC 원격 프로시저 호출 대상임을 프레임워크에 선언 인가해야 한다.

❌ Only plain objects, and a few built-ins, can be passed to Client Components from Server Actions.

원인: 서버 액션 함수 안에서 복잡한 DB 클래스 인스턴스(Ex: Prisma User 객체)나 Date 변수 자체를 쌩으로 return 해서 브라우저에게 던지려 했을 때 오류가 발생한다.
해결책: 브라우저는 그런 복잡한 메모리 클래스를 읽지 못한다. 리턴값을 내리기 전에 .toJSON() 으로 정제하거나 순수한 Object(문자열, 숫자, 불리언 조합의 DTO) 형태로 평탄화(Serialization) 해서 포장해 보내야 한다.

🏁 이번에 배운 내용 총정리

💡 시니어의 멘탈 모델
Server Actions는 결국 "숨겨진 POST API 자동 생성기" 이다. 너무나 사용이 편해진 만큼, 보안에 철저해야 한다! 저 함수는 URL을 타고 누구나 호출 가능하므로 내부 최상단에 항상 if (!user) throw Error("해킹 금지") 같은 인증/인가 가드를 반드시 세워두는 것을 잊지 말자.

📝 마무리 퀴즈

Q1. Server Action을 <form action=>에 연결했을 때 얻는 실무적 장점은 무엇인가?

✅ 정답: 폼 제출, 서버 실행, 캐시 갱신, UI 반환을 하나의 서버 왕복으로 묶을 수 있고, 서버 컴포넌트 폼은 자바스크립트가 없어도 기본 제출 흐름을 유지할 수 있다.

💡 상세 해설: Server Action은 단순히 API Route를 덜 쓰게 해주는 문법이 아니다. mutation을 서버 함수로 모델링하고, FormData를 통해 브라우저 기본 폼 흐름과 연결한다. 그래서 입력값을 모두 useState로 들고 있다가 JSON으로 포장하는 보일러플레이트를 줄일 수 있다.

Q2. Server Action이 클라이언트에서 호출 가능하다는 사실 때문에 반드시 지켜야 할 보안 원칙은 무엇인가?

✅ 정답: 모든 Server Action 내부에서 인증과 권한을 다시 검증해야 한다.

💡 상세 해설: 공식 문서도 Server Function/Action은 직접 POST 요청으로 호출될 수 있으므로 공개 API 엔드포인트처럼 다루라고 설명한다. 버튼이 화면에 안 보인다는 것은 보안이 아니다. auth(), 역할 검사, 소유권 검사, 입력 검증을 액션 내부에 둬야 한다. 영호라면 "UI 조건부 렌더링은 UX, 서버 검증은 보안"이라고 분리해서 리뷰한다.

Q3. 영철이의 테스트 타임: 댓글 작성 버튼을 누르면 즉시 댓글이 보이게 하고 싶다. 실패하면 에러 메시지도 보여야 한다. 어떤 조합이 자연스러울까?

✅ 정답: Server Action에 검증과 저장을 두고, 클라이언트에서는 useActionState로 pending/error 상태를 받고 필요하면 useOptimistic으로 낙관적 댓글을 표시한다.

💡 상세 해설: useActionState는 액션의 반환 상태와 pending을 UI에 연결한다. 낙관적 UI는 체감 속도를 높이지만, 서버 실패 시 되돌릴 수 있어야 한다. 저장 성공 뒤에는 관련 태그나 경로를 갱신해 서버 데이터도 맞춰야 한다. 액션은 편한 만큼 검증, 권한, 캐시 갱신이 한 세트다.

🐣 영철이의 퇴근 일기

오늘은 Server Action이 API Route를 없애는 마법이 아니라 mutation을 더 가까운 곳에서 설계하게 해주는 도구라는 걸 알았다. 폼과 서버 함수가 직접 이어지니 코드가 짧아졌지만, 그 함수가 외부에서 호출 가능한 서버 입구라는 사실도 더 선명해졌다.

💡 "Server Action은 편한 호출 문법이 아니라, 공개된 변경 지점이다."

앞으로 액션을 만들 때는 입력 검증, 인증/권한, 캐시 갱신, 반환 가능한 순수 객체를 체크리스트로 두겠다. 영호에게 리뷰를 요청하기 전에 "이 버튼을 우회해서 POST해도 안전한가?"를 먼저 내 코드에 물어봐야겠다.

🔗 더 알아보기

• Next.js Docs: Server Actions and Mutations