[Next.js] Server Action

실전 서버 액션

실제로 데이터베이스에 새로운 함수를 등록하는 서버 액션 함수를 등록해보겠습니다.

코드를 깔끔하게 관리하기 위해 action.ts 라는 백엔드 전용 파일을 src/ 안의 app/ 내부에 만듭니다.

코드를 살펴보면, 가장 먼저 파일 선언부에 use server를 선언해 모든 코드를 JS 번들에서 제외시킵니다.

'use server'

그 다음에 createProductAction 함수를 정의합니다. 매개변수로 FormData 타입의 객체를 인자로 받습니다.

export async function createProductAction(formData: FormData) { ... }

잠시후 프론트엔드에서 input 태그의 name 속성값을 기준으로 상품명과 가격 데이터를 안전하게 추출합니다.

const title = formData.get('title') as string
const price = Number(formData.get('price'))

그리고 데이터가 비어있지 않은지 검사하는 1차 유효성 검사하는 코드를 작성합니다.

if (!title || price <= 0) {
  throw new Error("상품명과 올바른 가격을 입력해주세요.")
}

그리고, 실제 데이터베이스에 저장하는 비즈니스 로직을 처리합니다. (실제로는 DB 연산이 일어납니다.)

완료되면, 성공 메시지를 반환합니다.

console.log(`[DB 저장 완료] 상품명: ${title}, 가격: ${price}원`)
 
return {
  success: true,
  messages: '시스템에 상품이 성공적으로 등록되었습니다.'
}

우리가 이전에 작성했던 Route Handlers와 비교하면 너무 평범한 자바스크립트 함수입니다.

더이상 Request 객체의 파싱도, HTTP 상태 코드를 반환할 일도 없습니다.

그저 데이터를 다루는 비즈니스 로직에 집중합니다.

이제 이 함수를 프론트엔드 컴포넌트 함수에서 어떻게 실행하는지 살펴보겠습니다.

먼저 src/ 내부의 app/ 폴더에 products/new 폴더를 만들고 page.tsx 파일을 만드세요.

export default function NewProductPage() {
  return (
    <div className={cn('p-10 font-sans max-w-md bg-white rounded-lg shadow-md mx-auto',
                       'mt-10 border border-gray-100')}
    >
      <h1 className="text-[#0070f3] mt-0 mb-3 mb-2 text-2xl font-bold">
        새로운 상품 통제소
      </h1>
      <p className="text-gray-500 text-sm mb-5">API 통신 코드가 증발한 혁신적인 폼 랜더링</p>
      <hr className="border-gray-200 my-5" />
      
      <form action={createProductAction as any} className="flex flex-col gap-4">
        <input
            type="text"
            name="title"
            placeholder="상품명을 입력하세요"
            required
            className={cn('p-3 border border-gray-300 rounded-md',
                          'focus:outline-none focus:ring-2 focus:ring-[#0070f3]',
                          'transition-all')}
        />
        
        <input 
            type="number"
            name="price"
            placeholder="가격을 입력하세요"
            required
            className={cn('p-3 border border-gray-300 rounded-md',
                          'focus:outline-none focus:ring-2 focus:ring-[#0070f3]',
                          'transition-all')}
        />
        <button 
          className="bg-blue-800 py-[12px] text-white rounded-sm" 
          type="submit"
        >
          상품 등록 시스템 기능
        </button>
      </form>
    </div>
  )
}

여기서 form 태그의 action 속성을 보시면, 최상단에서 방금 만든 서버 함수를 집어넣기만 하면 끝납니다.

간단한 방법이지만, 이면에는 현대 프레임워크에서 내부에 HTTP 통신 기술이 숨어있습니다.

우리가 서버 함수를 연결하는 순간 Next.js 프레임워크는 빌드 타임에 백그라운드에서 가짜 API 엔드포인트를 생성합니다.

그리고, 상품 등록 버튼을 누르면, 브라우저가 화면 새로고침을 막고, formData를 숨겨진 API 주소로 POST 요청을 합니다.

그러나 여기서 FE Engineer의 입장으로는 아쉬운 점을 발견해야 합니다.

지금 백엔드 함수는 success: true 라는 응답값을 반환하고 있긴 하지만, 사용자는 버튼을 누른 후 데이터가 저장되는 동안

아무런 시각적 피드백을 받지 못합니다. 로딩 스피너도 성공 메시지도 화면에 즉각적으로 뜨지 않습니다.

아래에서 이를 React 19에서 새로 등장한 상태 처리 훅을 통해서 해결할 것입니다.

useFormState를 통한 상태 UI 제어

위의 Server Actions를 통한 완벽해 보이는 코드에는 나쁜 UX라는 결함이 존재했습니다.

사용자가 행동을 하면, 데이터가 네트워크를 타고 백엔드 서버를 통해 날라가고

서버가 유효성 검사를 하고, 데이터베이스에 저장한 뒤 다시 응답을 돌려주는데, 물리적인 지연이 존재합니다.

하지만 지금 화면은 그 지연 화면동안 화면에 아무런 변화를 주지 않습니다. 버튼이 눌렸는지 시스템이 먹통인지 모릅니다.

사용자는 답답한 마음에 버튼을 연타하게 됩니다. 그 결과 똑같은 데이터가 서버로 수십번 전송되어 데이터베이스에

중복 저장 혹은 시스템 리소스가 고갈되는 끔찍한 대참사가 발생하고 맙니다.

과거 React와 SPA 시절에는 이 문제를 방어하기 위해 FE Engineer들이 isLoading 변수를 수동으로 관리해야 했습니다.

본질적인 비즈니스 기능보다 로딩 처리를 위한 보일러플레이트가 더 커진 상황입니다.

하지만, Server Actions이 등장하면서 이런 처리를 할 필요가 없는 우아한 도구가 생겼습니다.

바로 폼의 전송 상태를 프레임워크가 알아서 추적해주는 useFormStatus Hook 입니다.

이 훅을 사용하면, Server Actions에서 실행 중인지 아닌지 프레임워크가 감지하여 우리에게 알려줍니다.

이제 본격적으로 이 훅의 전체적인 기본 구조를 살펴봅시다.

단순히 실행 여부만 알려주는 것이 아니라 전송 상태 외에도, 폼 데이터의 내용, 사용된 HTTP 메서드, 연결된 서버 액션 함수를

부모 폼의 모든 속성들을 4가지 변수로 완전히 해체하여 저장합니다.

여기서 특히 가장 핵심 방어기제인 pending 상태값에 집중할 것입니다.

다만, 이 훅을 사용할 때는 지켜야 할 점이 있는데, 반드시 HTML 폼 태그의 내부 자식 컴포넌트 안에서만 호출되어야 합니다.

그 범위를 넘어서면 useFormStatus는 자신이 추적해야 할 부모 폼을 찾지 못해 에러를 발생시킵니다.

이는 React ContextAPI 원리로 동작하기 때문에 그렇습니다.

실제적으로, src/ 안의 app/ 폴더 안에 components/ 폴더를 만들고 SubmitButton.tsx 파일을 만드세요.

이 컴포넌트는 오직 자신을 감싸게 될 부모 폼의 상태만 바라보고 있는 상황입니다.

로직을 살펴보면, 브라우저의 동적인 상태를 다뤄야 하므로, 최상단에 클라이언트 컴포넌트임을 선언합니다.

'use client'

함수 내에서 useFormStatus를 호출하여 pending이라는 값을 빼냅니다.

export default function SubmitButton() {
  const { pending } = useFormStatus()
  // .... 아래에서 구현
}

이 pending 값 하나로 버튼의 비활성화 여부, 색상, 마우스 커서, 텍스트까지 통제합니다.

export deafult function SubmitButton() {
  const { pending } = useFormStatus()
  
  return (
    <button
      type="submit"
      disabled={pending}
      className={cn('p-4 border-none rounded-md font-bold transition-all shadow-md',
                    pending ? 'bg-gray-400 text-white cursor-not-allowed' : 'bg-[#0070f3]')}
    >
      {pending ? (
        <span>완전하게 저장 중</span>
      ) : (
        <span>상품 등록 시스템 기능</span>
      )}
    </button>
  )
}

이것을 앞서 작성한 form 태그 내부에 로 교체해줍니다.

이제 이 원리를 살펴보면, 사용자가 버튼을 누르는 순간 Server Action이 트리거됨과 동시에 

프레임워크가 백그라운드에서 폼의 상태를 pending=true로 변경합니다.

그 즉시 자식 컴포넌트인 버튼이 상태를 감지하고, 스타일들이 변하는데 버튼이 비활성화되어 중복 요청을 차단합니다.

그리고 서버 측 백엔드 함수가 저장을 완료하고, 응답을 돌려보내면, 프레임워크가 다시 폼의 상태를 원상복구합니다.

useActionState를 통한 Server Actions 결과 랜더링

만약 사용자가 실수로 악의적인 값을 입력하면 어떻게 될까요?

서버 로직에서는 분명 잘못된 값이라며 거부했지만, 현재 클라이언트 화면은 이 상황을 전혀 알지 못합니다.

물리적으로 분리된 백엔드와 프론트엔드 사이에 결과 상태를 알려주는 Bridge가 끊어져 있는 것입니다.

과거 SPA 시절에는 이 끊어진 Bridge를 잇기 위해 try-catch 문으로 네트워크 에러를 잡고

상태 변수에 서버의 메시지를 수동으로 밀어넣는 방식을 택했습니다.

하지만, Next.js 15+가 채택한 React 19 환경에서는 이 모든 고민을 해결해주는 무기 useActionState를 제공합니다.

이 훅은 Server Actions가 실행을 마치고 뱉어내는 결과물을 프레임워크가 백그라운드에서 낚아채어

화면의 상태 변수에 즉각적으로 동기화시켜주는 혁명적인 동기화 도구입니다.

기본 형식은 다음과 같이 작성합니다.

이 훅은 프레임워크에 2개의 필수 인자를 전달받아 동작하는데

첫번째 actionFunction은 우리가 실행하고자 하는 백엔드 Action Server Function입니다.

두번째 initialState는 서버가 아직 아무런 응답을 주지 않은 초기 상태의 뼈대입니다.

이 2가지 필수 인자를 적어넣으면 프레임워크는 내부적인 연결 작업을 마친 뒤, 3가지 핵심 요소를 배열로 반환합니다.

첫번째 state는 서버가 로직 처리를 마치고 클라이언트로 보낸 최신의 상태 객체입니다.

두번째 formAction은 기존의 서버 함수를 프레임워크가 폼 전송 규격에 맞게 감싸서 업그레이드한 새로운 실행기입니다.

세번째 isPending은 네트워크 상태를 감지한 로딩 화면 통제권입니다.

이 완벽한 구조의 훅을 시스템에 적용하기 위해서는 백엔드의 서버 함수를 살짝 수정해야 합니다.

프레임워크의 규칙에 따라 무조건 첫번째 인자로 이전 상태를 건네받도록 강제되기 때문입니다.

그래서 다음과 같이 함수 기본 형태를 수정합니다.

useActionState를 사용하면 Next.js가 이전 상태를 첫번째 인자로 억지로 주입합니다.

export interface ProductFormState {
  success: boolean
  message: string
  attemptCount: number
}
 
export async function createProductAction(
  prevState: ProductFormState,
  formData: FormData
): Promise<ProductFormState> { ... }

억지로 주입하는 이유는, 로직에 포함된 attemptCount 때문입니다.

먼저 처음에 attemptCount를 +1 증가시킵니다.

const currentAttempt = prevState.attemptCount + 1

만약 버튼을 누르다가 에러를 트리거 당하고, 다시 제출 버튼을 누르면,

백엔드 서버는 클라이언트가 보낸 과거의 상태를 기억하고 있다가 시도 횟수를 누적해서 추적할 수 있습니다.

클라이언트에 새로운 변수를 선언하지 않아도 브라우저와 서버가 같은 컨텍스트로 공유하는 것입니다.

다음은 방어로직인데, 과거처럼 error를 던지는 일은 하지 않습니다.

if (!title || title.length < 2) {
  return {
    success: false,
    message: "상품명은 최소 2글자 이상 입력해야 합니다",
    attemptCount: currentAttempt
  }
}
 
if (price <= 0) {
  return {
    success: false,
    message: "가격은 0원보다 커야 합니다.",
    attemptCount: currentAttempt
  }
}

그리고 비동기 setTimeout을 이용해 강제로 1.5초의 네트워크 딜레이를 줍니다.

await new Promise(resolve => setTimeout(resolve, 1500))

마지막으로 규격화된 성공 상태를 반환합니다.

return {
  success: true,
  message: `성공적으로 등록되었습니다: ${title}`,
  attemptCount: currentAttempt
}

이제 직접 페이지 컴포넌트에서 이것을 적용해봅시다. 앞서 만든 src/app/products/new에 있는 page.tsx에 적용합니다.

export default function NewProductPage() {
  const initialState: ProductFormState = {
    success: false,
    message: '',
    attemptCount: 0
  }
  
  const [state, formAction] = useActionState(createProductAction, initialState)
  
  return (
   <div className={cn('p-10 font-sans max-w-md bg-white rounded-lg shadow-md mx-auto',
                       'mt-10 border border-gray-100')}
    >
      <h1 className="text-[#0070f3] mt-0 mb-3 mb-2 text-2xl font-bold">
        새로운 상품 통제소
      </h1>
      <p className="text-gray-500 text-sm mb-5">API 통신 코드가 증발한 혁신적인 폼 랜더링</p>
      <hr className="border-gray-200 my-5" />
      
      <form action={formAction} className="flex flex-col gap-4">
        <input
            type="text"
            name="title"
            placeholder="상품명을 입력하세요"
            required
            className={cn('p-3 border border-gray-300 rounded-md',
                          'focus:outline-none focus:ring-2 focus:ring-[#0070f3]',
                          'transition-all')}
        />
        
        <input 
            type="number"
            name="price"
            placeholder="가격을 입력하세요"
            required
            className={cn('p-3 border border-gray-300 rounded-md',
                          'focus:outline-none focus:ring-2 focus:ring-[#0070f3]',
                          'transition-all')}
        />
        <SubmitButton />
        {
          state.message && (
            <div className={cn('p-4 mt-2 rounded-md border',
                               state.success ? 'bg-green-50' : 'bg-red-800')}
            >
              <p className="m-0 mb-1 font-bold text-sm opacity-80">
                시도 횟수: {state.attemptCount}회
              </p>
              <p className="m-0 font-semibold">
                {state.message}
              </p>
            </div>
          )
        }
      </form>
    </div>
  )
}

단계별로 살펴보면, 사용자가 아무 버튼도 누르지 않은 최초의 상태 initialState를 정의합니다.

두번째로, useActionState 훅을 호출하여 서버 함수와 초기값을 인자로 넣어 최신 상태의 state와 폼 액션을 반환받습니다.

세번째로, formAction은 form 태그의 action 속성으로 집어넣습니다.

마지막으로, 실시간으로 변하는 state 값을 활용해 조건부 랜더링을 수행합니다.

캐싱의 역설 - revalidatePath

위에서 HTML 폼을 통해 새로운 상품을 등록하고, 상품 목록 페이지로 이동했는데, 새로 넣은 데이터가 없는 현상이 발생합니다.

이 현상은 역설적이게도 Next.js 프레임워크가 너무나 빠르고 효율적으로 일하고 있어서 발생한 캐싱의 역설입니다.

상품 목록 페이지의 코드를 보며 상황을 진단해보겠습니다. src/app/products에 page.tsx 코드입니다.

export default async function ProductsPage() {
  const res = await fetch('http://localhost:3000/api/products', { cache: 'force-cache' })
  const products = await res.json()
  
  return (
    <div style={{ padding: '40px', fontFamily: 'sans-serif' }}>
      <h1>전체 상품 통제소</h1>
      <ul>
        {products.map((p: any) => (<li key={p.id}>{p.title} - {p.price}원</li>))}
      </ul>
    </div>
  )
}

실무에서는 서버 부하를 위해 명시적으로 force-cache를 부여하지만, 이렇게 되면 캐시 메모리를 놓아주지 않아

업데이트 전 옛날 데이터를 스냅샷을 저장해둔 상태입니다.

사용자가 다시 목록 페이지에 접속했을 때 프레임워크는 DB를 다시 쳐다보지도 않은 채

낡은 스냅샷을 0.01ms 만에 브라우저로 던져버립니다.

새로운 데이터가 추가되었으니 들고 있는 낡은 스냅샷을 당장 버리고, 화면을 새롭게 다시 그려야 합니다.

이 때 아키텍트가 가져온 핵심 무기가 revalidatePath 입니다. (캐시 무효화)

특정 경로에 묶여있는 낡은 캐시 데이터를 강제로 유통기한 만료시키는 파괴 마법입니다.

이것을 적용시키기 위해 지난번에 작성했던 action.ts 파일을 수정하겠습니다.

마지막 성공 처리 부분에 revalidate 기능을 추가하고, 저장이 완료되면, 갱신된 상품 목록 페이지로 이동시키겠습니다.

import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'
 
export interface ProductFormState {
  success: boolean
  message: string
  attemptCount: number
}
 
export async function createProductAction(
  prevState: ProductFormState,
  formData: FormData
) {
    // .... 앞서 행했던 유효성 검사 등의 로직
    // .... 실제 데이터베이스의 저장 로직 수행
    revalidatePath("/products")
    
    redirect("/products")
}

revalidatePath를 불러온 next/cache는 Next.js의 거대한 캐시 메모리를 직접 조작하고 통제할 수 있는

백엔드 전용 API들을 모아둔 심장부이며

redirect를 불러온 next/navigation은 서버와 클라이언트를 넘나들며, 사용자의 위치와 동선을

강제로 조작할 수 있는 라우팅 통제실입니다.

revalidatePath(...)가 실행되는 찰나, 백그라운드에서는 무자비한 철거작업이 일어납니다.

주소와 관련된 모든 캐시 데이터와 화면 껍데기를 폐기합니다.

그리고, redirect(...)가 가동되어 강제로 화면 주소를 이동시킵니다.

이 때, 사용자가 목록 페이지에 도착하는 순간 Next.js 프레임워크는 캐시를 꺼내주려 메모리 창고를 열지만

텅텅 비어있음을 확인하고, 그제서야 데이터베이스 원본 창고로 달려가 데이터 조회 명령을 내립니다.

그렇게 하여 가장 완벽하고 신선한 데이터를 가져와 화면에 다시 랜더링시킵니다.

현재까지 배운 것이 바로 현대 Next.js 15+ 개발의 교과서적인 변이 패턴(Mutation Pattern) 입니다.

useOptimistic - 낙관적 UI 업데이트

사용자가 상세 페이지에서 좋아요 버튼을 눌렀다고 가정합시다.

데이터가 브라우저를 출발해 서버까지 날아갔다가 데이터베이스를 수정하고 다시 돌아오기까지는

아무리 최적화를 잘해도 물리적인 네트워크 지연이 발생합니다.

이러한 물리적인 네트워크 지연시간을 사용자 입장에서 0초로 만들어버리는 궁극기가 낙관적 업데이트입니다.

낙관적 업데이트란, 우리가 서버로 보낸 요청이 무조건 성공할 것이라고 가정하고 화면을 먼저 그리는 것입니다.

만약 서버에서 진짜 성공 응답이 오면 그대로 두면 되고, 만약 에러가 발생하면 재빨리 원래 상태로 되돌립니다.

Next.js 15+가 채택한 React 19 환경에서는 복잡한 상태복구 과정을 프레임워크가 알아서 완벽하게 처리해주는

useOptimistic()이라는 경이로운 훅을 제공합니다.

본격적으로 이 훅의 기본 구조부터 살펴보겠습니다.

const [optimisticState, addOptimistic] = useOptimistic(currentState, reducerFunction)

useOptimistic은 2가지 인자를 받는데

첫째는 데이터베이스가 알고있는 진짜 상태 초기값입니다.

둘째는 우리가 낙관적인 값을 넣었을 때 화면의 상태를 변화시킬지 결정하는 업데이트 함수입니다.

훅을 실행하면 2개의 값을 반환합니다.

첫번째 optimisticState는 평소에는 진짜 상태를 보여주다가, 이벤트 발생 시 즉시 가짜 상태로 변신합니다.

두번째 addOptimistic은 그 가짜 상태를 발동시키는 트리거 역할을 합니다.

이제 앞서 작성했던 action.ts 코드에 이 원리를 적용해보겠습니다.

먼저, 백엔드 서버 업데이트 함수에 상품의 좋아요 상태를 변경하는 간단한 함수를 추가하겠습니다.

export async function toggleProductLikeAction(
  productId: string,
  newLikeStatus: boolean
) { ... }

그리고 함수 내의 로직을 보면, 의도적으로 1초의 네트워크 대기 시간을 추가합니다.

await new Promise(resolve => setTimeout(resolve, 1000))

낙관적 업데이트가 실패했을 때 롤백이 잘되는지 검증하기 위해 10% 확률로 Error를 던집니다.

if (Math.random() < 0.1) {
  throw new Error("서버 통신 중 알 수 없는 에러가 발생했습니다.")
}

무사히 통과하면 데이터베이스를 업데이트하고, revalidatePath로 낡은 캐시를 무효화합니다.

console.log(`[DB 업데이트] 상품 ${productId}의 좋아요 상태가 ${newLikeStatus}로 변경`)
revalidatePath(`/products/${productId}`)
return newLikeStatus

이 서버는 1초간 시스템적으로 지연되기 때문에, 사용자는 좋아요를 누르고 1초 동안 스피너를 보며 기다려야 했지만

useOptimistic 훅을 사용해 이 1초를 마술처럼 지워버릴 것입니다.

본격적인 마법을 부리기 위해 상품 상세 페이지에 장착할 LikeButton.tsx를 작성합시다.

먼저 이 함수는 React 훅을 사용할 예정이므로, 클라이언트 컴포넌트임을 선언해줍니다.

'use client'

그리고 함수를 작성하는데 productId와 initialLiked 변수를 props로 받습니다.

export default function LikeButton(
  { productId, initialLiked } :
  { productId: string, initialLiked: boolean }
) { ... }

useOptimistic 훅을 통해, 낙관적 변수와 낙관적 변수를 트리거하는 함수를 받을 것입니다.

const [optimisticLiked, addOptimisticLike] = useOptimistic(
  initialLiked,
  (currentState, optimisticValue: boolean) => optimisticValue
)

이 컴포넌트의 핵심은 폼이 제출될 때 실행되는 handleLike 함수에 있습니다.

사용자가 하트를 누르면, 시스템은 바뀔 상태인 newLikeStatus를 계산하고

서버로 데이터를 보내기도 전에, addOptimisticLike 함수를 먼저 호출해버립니다. 이 순간 상태가 즉시 바뀝니다.

서버에 toggleProductLikeAction이 백그라운드에서 조용히 실행되며 1초의 지연시간을 갖습니다.

하지만 사용자의 화면은 완성되어 있으므로, 사용자는 지연시간을 느끼지 못합니다.

서버 에러가 여기서 발생한다면, catch 블록이 실행되면서 프레임워크는 가짜 상태를 폐기합니다.

그리고 하트 상태를 다시 롤백시킵니다.

const handleLike = async () => {
  const newLikeStatus = !optimisticLiked
  
  addOptimisticLike(newLikeStatus)
  
  try {
    await toggleProductLikeAction(productId, newLikeStatus)
  } catch (error) {
    alert("좋아요 처리에 실패했습니다. 시스템이 원래 상태로 복구됩니다.")
  }
}

최종적으로 UI는 form 태그 안에 있는 버튼으로 구성합니다.

return (
  <form action={handleLike}>
    <button>좋아요 - {optimisticLiked ? 'OK' : 'NO'}</button>
  </form>
)

HTTP의 무상태성과 쿠키(Cookie)

웹 브라우저와 서버가 통신하는 기반 프로토콜인 HTTP 프로토콜은 절대적인 아키텍처적 특징이 있습니다.

바로, 무상태성(Stateless) 즉 서버가 클라이언트의 이전 요청을 전혀 기억하지 못한다는 뜻입니다.

이것을 실제 예시로 적용해보면, 첫번째로 ID와 PW를 입력하여 로그인을 성공했더라도

두번째 요청으로 장바구니 리스트를 보여달라고 하면, 로그인하라며 요청을 거절합니다.

이는 어찌보면 당연한데, Amazon이나 Google 같은 거대한 서버 입장에서는 전세계 동시 접속자를 동시에 처리해야 합니다.

만약 서버가 한명 한명 로그인 상태와 방문 기록을 모두 메모리에 쥐고 있어야 한다면, 메모리 초과로 터질 겁니다.

그러면 서버가 연결을 기억하지 못하고 매번 연결을 끊어버린다면, 어떻게 로그인은 유지될까요?

이 무상태성의 HTTP 한계를 극복하기 위해 네트워크 엔지니어들이 발명한 것이 쿠키(Cookie) 입니다.

이 원리는 클라이언트가 처음 서버에 접속해서 로그인을 성공하면,

서버는 응답을 보낼 때, 클라이언트의 신분증 역할을 하는 쿠키를 구워서 브라우저에게 건네줍니다.

브라우저는 이 쿠키를 저장해두고, 그 다음부터 서버에 새로운 요청을 보낼 때 마다

브라우저는 이 쿠키를 HTTP 요청 헤더에 담아서 보냅니다. 서버는 이 쿠키를 통해 매번 새롭게 식별합니다.

실제 서버가 브라우저에게 쿠키를 구워줄 때 사용하는 응답 헤더의 모습을 살펴보면 아래와 같습니다.

Set-Cookie라는 명령을 통해 sessionId라는 민감한 값을 전달하는데, 그 뒤에 Secure, HttpOnly, SameSite라는 것은

쿠키를 보낼 때 아키텍트가 빠뜨려서는 안될 핵심 보안 속성입니다. Cookie는 JWT 같은 민감한 정보를 담고 있으므로

해커들의 1순위 탈취 타겟이 됩니다. 그러므로 위 보안 속성을 반드시 이해해야 합니다.

첫번째, Secure 속성은 오직 https 즉 암호화된 안전한 연결 상태에서만 브라우저가 서버로 쿠키를 전송하라는

강력한 자물쇠 역할입니다. 공용화된 와이파이에서 패킷을 가로채려 해도 일반 http 환경에선 브라우저가 쿠키를 숨깁니다.

두번째, httpOnly 속성은 브라우저의 자바스크립트 코드로 쿠키에 접근하는 것을 시스템 레벨에서 원천 차단합니다.

해커가 악성 코드를 심어놓고 쿠키를 훔쳐가려는 XSS 공격을 시도해도, 자바스크립트는 쿠키를 읽을 수 없습니다.

따라서 우리는 로그인 상태를 확인하거나, 토큰을 검증할 때 반드시 서버 컴포넌트나 미들웨어에서 쿠키를 열어봐야 합니다.

세번째, SameSite=Strict 속성은 사용자가 머물고 있는 사이트의 도메인과 쿠키가 처음 만들어진 도메인이

완벽하게 동일할 때만 쿠키를 전송하도록 엄격하게 제한합니다.

사용자를 교묘하게 속여, 해커의 악성 사이트로 의도치 않은 송금을 보내게 만드는 CSRF 위조 공격을 방어합니다.

Cookies() - Server Actions 내에서의 쿠키 제어

과거 순수 React와 SPA 환경에서는 주로 브라우저가 제공하는 document.cookie를 통해 JS로 직접 제어했습니다.

하지만 이 방식은 보안 취약점인 XSS 공격에 무방비하게 노출된다는 단점이 있습니다.

이러한 보안의 구멍을 틀어막기 위해 안전한 백엔드 서버의 권한으로 쿠키를 구워야만 합니다.

Next.js 프레임워크는 이를 위해 next/headers 라는 모듈을 제공합니다.

이 모듈은 클라이언트와 서버가 통신할 때 발생하는 거대한 HTTP 헤더 정보를 백엔드에서 조회하고 조작하는

아주 강력한 통제소입니다. 그리고, 통제소 안에 서버 전용 함수인 cookies()가 들어있습니다.

이것을 Server Actions 내부에서 호출하면, 서버가 클라이언트에게 응답을 보낼 때 HTTP 헤더에 안전하게

쿠키를 심어서 브라우저로 쏘아보낼 수 있게 됩니다.

실전으로, 사용자가 선택한 다크모드 설정값을 서버에 기억시키는 실전 코드를 작성해볼게요.

앞서 작성했던 action.ts에 다음 같은 코드를 추가할 것입니다.

먼저, next/headers 모듈에서 cookies 함수를 불러옵니다.

import { cookies } from 'next/headers'

캐시 무효화하는 revalidatePath 모듈도 불러옵니다.

import { revalidatePath } from 'next/cache'

그 다음 백엔드 액션 함수를 만듭니다.

export async function toggleThemeAction() { ... }

다음으로 주의할 점은 Next.js 15+ 부터 cookies 함수가 비동기적으로 작동한다는 것입니다.

따라서 await 키워드를 붙여 메모리에서 쿠키 저장소를 읽어올 때까지 기다려야 합니다.

const cookieStore = await cookies()

저장소를 가져왔다면, get 메소드를 사용해 기존의 테마 쿠키값을 읽어옵니다.

const currentTheme = cookieStrore.get('theme')?.value || 'light'

그리고 현재 상태의 반대값으로 새로운 테마를 결정합니다.

const newTheme = currentTheme === 'light' ? 'dark' : 'light'

그리고 의도적으로 네트워크 지연을 줍니다.

await new Promise(resolve => setTimeout(resolve, 1000))

브라우저에게 새로운 쿠키를 굽도록 명령합니다.

cookieStore.set('theme', newTheme, {
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'lax',
  maxAge: 60 * 60 * 24 * 365,
  path: '/'
})

마지막으로 화면이 최신 쿠키를 반영할수 있도록 루트 레이아웃의 캐시를 무효화합니다.

revalidatePath('/', 'layout')

이제 백엔드 로직이 완료되었으나, Server Actions를 호출하는 버튼 컴포넌트를 만들어봅시다. (ThemeToggleButton.tsx)

이 때 우리는 React 18부터 도입된 훅인 useTransition을 사용할 것입니다.

여기서 가벼운 버튼 클릭 이벤트에서 useFormStatus를 사용한다면, 비동기 서버 액션을 호출하게 될 것이고

데이터를 서버로 보내고, 응답을 기다리는 시간동안 브라우저 메인 스레드가 멈춰버리는 병목 현상이 발생하게 될 것입니다.

이를 막기 위해 고안된 것이 useTransition이기 때문입니다. 상태변화의 우선순위를 뒤로 미루는 훅입니다.

래퍼 함수 안에 무거운 서버 통신 작업을 집어넣으면 React 엔진은 백그라운드에서 천천히 처리해도 된다고 판단합니다.

덕분에 서버 통신이 일어나는 동안에도 브라우저 스레드는 멈추지 않습니다. 따라서 사용자는 논 블로킹 경험을 유지합니다.

먼저 상태 변화가 있으므로, use client 지시어를 사용합니다.

'use client'

그리고 함수를 만듭니다.

export default function ThemeToggleButton() { ... }

함수 내에서는 isPending 상태와 startTransition 래퍼 함수를 정의해 useTransition을 사용합니다.

여기서 isPending은 서버 통신이 일어날 때 true로 바뀌어 버튼이 잠기고, 텍스트를 변경해주는 상태값입니다.

const [isPending, startTransition] = useTransition()

마지막으로 toggle 함수를 발동시킬 때 서버 통신이 일어날텐데 그것을 startTransition으로 감쌉니다.

const handleTransition = () => startTransition(() => { toggleThemeAction() })

이제 브라우저의 쿠키에서 어떤 마법이 일어나는지 살펴보세요.

특히 HttpOnly 열에 체크 표시가 켜져있는 것을 보며, 해커로부터 안전한 서버 사이드 쿠키 제어를 경험합니다.

Redirect와 HTTP 300번대 상태코드

올바른 흐름 제어를 위해 데이터를 처리하고 나서 사용자의 동선을 어떻게 처리할지 정하는 것이 중요합니다.

사용자가 로그인 성공, 결제 완료 등의 무거운 POST 처리가 끝난 직후에 사용자를 원래 있던 화면에 방치하면 안됩니다.

무심코 브라우저의 새로 고침 버튼을 눌렀을 때 중복 제출이 일어나는 대참사가 일어날 수 있기 때문입니다.

이러한 중복 제출의 비극을 막고, 안전한 화면으로 인도하기 위해 PRG 패턴입니다.

이 패턴을 제어하는 핵심 기술이 HTTP 상태 코드 300번대 입니다. 즉, 리다이렉션입니다.

클라이언트가 특정 주소로 요청을 보냈을 때 찾는 데이터나, 다음으로 가야할 곳을 지정해주는 상태 코드입니다.

PRG 패턴 통신 흐름을 살펴보겠습니다.

먼저 브라우저가 POST 메소드(예: /login)로 요청을 보내면, 서버가 처리를 완료합니다.

이어서 서버는 302 Found라는 상태 코드와 함께 /dashboard로 가라는 Location 응답을 브라우저에게 보냅니다.

이 응답을 받은 브라우저는 즉시 새로운 주소로 이동해 GET 메소드로 /dashboard 화면을 요청하고

마지막으로 서버가 200 OK를 보내어 화면에 필요한 데이터를 내려줍니다.

이 때 서버가 브라우저를 강제로 이동시킬 때 보내는 HTTP 응답 헤더는 아래와 같습니다.

첫줄에 HTTP/1.1 302 Found 라는 300번대 상태 코드가 명시되어 있습니다.

둘째 줄에 Location: /dashboard 라는 헤더가 반드시 짝꿍으로 따라다닙니다.

또한 마지막 줄에 Set-Cookie 헤더를 통해 세션ID를 발급하면서 httpOnly와 Secure 같은 강력한 보안 속성을 함께 부여합니다.

이 짧은 응답을 받은 브라우저의 내부에서는 놀라운 자동화 과정이 일어나는데

브라우저 엔진은 302 Found라는 상태 코드를 보는 순간 화면에 아무것도 랜더링하지 않고

즉시 Location 줄의 해당 path로 시선을 돌립니다.

그리고 사용자가 클릭하지 않았음에도 새로운 주소로 두번째 GET 요청을 자동으로 날려버립니다.

그러면, 300번대 코드에 대해 자세히 알아볼까요?

1. 301: Moved Permanently (영구 이사)

이 페이지는 영원히 이사갔으니, SEO 업데이트가 필수적입니다.

2. 302: Found (임시 여행)

잠깐 임시로 이동한다는 뜻입니다. 그런데 초창기 웹 브라우저들은 302 코드를 해석할 때 버그를 가지고 있었습니다.

사용자가 POST 메소드로 무거운 데이터를 보냈는데, 서버가 302 리다이렉트를 지시하면

브라우저가 이동할 주소로 2번째 요청을 보낼 때 원래의 POST 메소드를 잊어버리고

제멋대로 GET 메소드로 둔갑시켜 버린 것입니다. 당시에는 결함이었으나, 이후 웹 사이트에서는 이 결함을 이용했습니다.

앞서 말한 PRG 패턴을 구현하는데 사용해버린 것입니다. 사실상의 웹 표준처럼 굳어져 버립니다.

그러나 현대적인 API 시대에서는 POST, PUT 메소드의 성질을 훼손하지 않고

POST로 보냈으면, 리다이렉트된 주소로도 반드시 POST로 도착해야 한다는 엄격하게 유지해야 하는 상태가 되었습니다.

이제 이 강력한 무기를 Next.js에 직접 장착할 차례입니다.

과거 Page Router 시절에는 next/router 모듈을 사용했지만

App Router가 도입되면서 프레임워크의 라우터 아키텍처는 완전히 새롭게 개편되었습니다.

Next.js는 이제 서버와 클라이언트 환경 모두에서 URL 이동과 경로 탐색을 전담하는 거대한 사령부인

next/navigation 모듈을 제공합니다.

실제 실무 환경에서 redirect() 함수는 수없이 많이 사용되는데

사용자가 쇼핑몰 환경에서 결제를 완료한 직후 영수증 화면으로 안전하게 넘겨야 할 때

권한이 없는 게스트 사용자가 어드민 페이지에 접근하려고 할 때 즉시 로그인 화면으로 차단할 때

새로운 게시글 작성을 성공적으로 마친 뒤 전체 목록 페이지로 사용자를 튕겨내 버릴 때

아주 유용하게 사용됩니다.

본격적으로 action.ts 모듈을 작성해보겠습니다.

먼저, 다음과 같은 함수를 작성합니다.

export async function createPostAction(formData: FormData) {...}

폼 데이터에서 제목을 꺼내 DB에 저장합니다.

const formData = formData.get('title') as string
console.log(`[DB 저장] 새로운 게시글 ${title}이 저장되었습니다.`)

그리고 쿠키를 구워줍니다.

const cookieStore = await cookies()
cookies.set('author_badge', 'true', { httpOnly: true, secure: true })

마지막 단계에서 게시글 리스트로 리다이렉트합니다.

redirect('/posts')

하지만 이 리다이렉트 내부에는 놀랍고도 위험한 비밀 하나가 숨어있습니다.

Next.js의 리다이렉트 함수는 호출되는 순간 내부적으로 NEXT_REDIRECT라는 특수한 에러를 던집니다.

Server Actions 도중에 리다이렉트가 결정되었다면 그 아래에 남아있는 코드는 더 이상 실행 필요없는 낭비이기 때문입니다.

프레임워크가 NEXT_REDIRECT 코드를 낚아채서 즉시 서버 함수의 실행을 중단시키고

브라우저에 HTTP 303 헤더와 Location을 쏘아 보냅니다.

그런데 이 리다이렉트가 함수가 코드의 흐름을 끊어버린다는 독특한 패턴 때문에

치명적인 함정에 빠질 수 있는데 바로 예외처리를 위한 try - catch 블록 안에서 리다이렉트를 무심코 사용했다가

리다이렉션이 아예 먹통이 되는 버그입니다.

이 무서운 함정을 피하는 방어 코드를 살펴봅니다. 명심 할 점은 반드시 리다이렉트는 try-catch 블록의 바깥에서 구현합니다.

export async function safeCreateServerAction(formData: FormData) {
  let isSuccess = false
  
  try {
   // ..... 내부 로직
   isSuccess = true
  } catch {
   // ..... 실패했을 때 로직
  }
  
  if (isSuccess) redirect("/posts")
}

하지만 부득이하게 catch 블록 안에서 사용하여야 한다면, 이 에러가 리다이렉트 에러인지 체크해서 던져주어야 합니다.

try {
  const title = formData.get('title') as string
  if (!title) throw new Error("제목이 비어있습니다.")
  console.log('DB 저장 로직 완료')
  isSuccess = true
  
} catch(e) {
  if (isRedirectError(e)) throw error
  console.error('에러 발생')
  return { success: false, message: '게시글 작성에 실패했습니다' }
}