🚀 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("해킹 금지") 같은 인증/인가 가드를 반드시 세워두는 것을 잊지 말자.

📝 마무리 퀴즈

배웠으면 한 번 비틀어서 확인해봐야 해.

1. 상황: 영철이가 회원 정보 수정 페이지에서 전면 클라이언트 컴포넌트(use client) 화면을 개발 중이다. 취미 박스를 <input> 10개짜리 거대한 폼으로 만들었는데, 영철이는 저장 버튼 이벤트(onClick) 내부에서, 10개의 값을 하나하나 useState 로 다 묶어서 끙끙대다가 객체를 만들고 서버 액션 함수 saveHobbies({ 묶은 정보 객체 }) 로 쏘아보냈다.
   이 끔찍한 리액트 렌더링 낭비 보일러플레이트를 단숨에 날려버릴 수 있는 영호 리드의 "폼 액션 네이티브 객체 접근법" 리팩토링 조언은 무엇일까?

정답 및 해설:
10개의 <input> 각각에 고유의 name 속성(name="hobby1", name="hobby2")을 부여하는 것이 핵심이다.
그리고 어설픈 useState 연동(제어 컴포넌트)을 전부 삭제하고, 폼 태그 상단에 <form action={saveHobbies}> 라고 서버 액션을 바로 꽂아버린다!
이러면 넘겨받는 서버 액션 함수의 파라미터는 자동으로 든든한 formData 브라우저 네이티브 객체가 되며, 우리는 formData.get('hobby1') 로 우아하고 가볍게(비제어 방식) 값을 쏙쏙 뽑아먹어 성능 최상의 속도를 낼 수 있다.

🐣 영철이의 퇴근 일기

오늘은 정말 넥스트의 꽃이라 불리는 'Server Actions' 를 배우면서 신세계를 경험했어! 예전엔 폼 하나 제출하려면 API 만들고, 페칭 로직 짜고, 로딩 상태 관리하느라 진이 다 빠졌는데... 이제는 함수 하나로 이 모든 게 연결되다니 정말 충격적이었어.

💡 오늘의 교훈: "복잡한 API 엔드포인트 설계에 매몰되지 말자. use server 액션 하나로 프론트와 서버를 우아하게 잇고, 사용자에게는 useActionState 로 끊김 없는 경험을 선물하자!"

영호 리드 님이 "편해진 만큼 보안은 네가 챙겨야 한다" 고 따끔하게 조언해 주실 때, 단순히 기능을 구현하는 걸 넘어 안전한 서비스를 만드는 게 개발자의 진짜 실력이라는 걸 다시 한번 깨달았어. 오늘 너무 열심히 달렸더니 당분 보충이 시급해. 집에 가는 길에 달달한 초코바 하나 사 먹어야지! 내일은 더 '강력하고 안전한' 액션을 짜는 개발자가 될 거야! 🐣

🔗 더 알아보기

• Next.js Docs: Server Actions and Mutations