Next.js 15 서버 액션으로 폼 데이터 처리하기 완벽 가이드

• API 라우트 불필요: 별도의 엔드포인트 없이도 서버 로직 실행 가능해요
• 타입 안정성: TypeScript와 완벽하게 통합되어 타입 추론이 자동으로 돼요
• 자동 재검증: 데이터 변경 후 revalidatePath로 캐시 갱신이 쉬워요
• 프로그레시브 인핸스먼트: JavaScript 없이도 폼이 작동해요

npx create-next-app@latest my-form-app
cd my-form-app
npm install zod react-hook-form @hookform/resolvers

app/
├── actions/           # 서버 액션 모음
│   └── form-actions.ts
├── components/        # 재사용 컴포넌트
│   └── forms/
│       └── ContactForm.tsx
├── lib/              # 유틸리티 함수
│   ├── validations.ts  # Zod 스키마
│   └── types.ts       # TypeScript 타입
└── (routes)/         # 페이지 라우트
    └── contact/
        └── page.tsx

# 데이터베이스
DATABASE_URL="your-database-url"

# 이메일 전송 (예: Resend)
RESEND_API_KEY="your-api-key"

# 기타 필요한 설정
NEXT_PUBLIC_SITE_URL="http://localhost:3000"

클라이언트에서 접근해야 하는 환경 변수만 NEXT_PUBLIC_ 접두사를 붙이세요. 서버 액션에서만 쓰는 건 접두사 없이 사용하면 돼요. 이거 처음엔 저도 헷갈렸는데, 보안상 정말 중요해요!

{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true,
    "esModuleInterop": true,
    "moduleResolution": "bundler",
    "target": "ES2022",
    "lib": ["ES2022", "dom"]
  }
}

• Next.js 15 프로젝트 생성 완료
• 필수 패키지 설치 (zod, react-hook-form)
• 디렉토리 구조 정리
• 환경 변수 설정
• TypeScript 설정 최적화
• VS Code 확장 프로그램 설치

import { z } from 'zod';

const userSchema = z.object({
  email: z.string().email('올바른 이메일을 입력해주세요'),
  password: z.string()
    .min(8, '비밀번호는 최소 8자 이상이어야 해요')
    .regex(/[A-Z]/, '대문자를 하나 이상 포함해야 해요')
    .regex(/[0-9]/, '숫자를 하나 이상 포함해야 해요'),
  age: z.number()
    .min(14, '14세 이상만 가입할 수 있어요')
    .max(120, '나이를 확인해주세요'),
  terms: z.boolean().refine(val => val === true, {
    message: '이용약관에 동의해주세요'
  })
});

export async function createUser(formData: FormData) {
  'use server';
  
  const rawData = {
    email: formData.get('email'),
    password: formData.get('password'),
    age: Number(formData.get('age')),
    terms: formData.get('terms') === 'on'
  };
  
  try {
    const validatedData = userSchema.parse(rawData);
    // 검증 통과! 이제 DB에 저장하면 돼요
    await db.user.create({ data: validatedData });
    return { success: true };
  } catch (error) {
    if (error instanceof z.ZodError) {
      return { 
        success: false, 
        errors: error.flatten().fieldErrors 
      };
    }
    throw error;
  }
}

function validateEmail(email: string) {
  const errors = [];
  
  if (!email) {
    errors.push('이메일은 필수예요');
  } else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
    errors.push('이메일 형식이 아니에요');
  } else if (email.length > 255) {
    errors.push('이메일이 너무 길어요');
  }
  
  return errors;
}

function validatePassword(password: string) {
  const errors = [];
  
  if (!password) {
    errors.push('비밀번호는 필수예요');
  } else {
    if (password.length < 8) {
      errors.push('최소 8자 이상 입력해주세요');
    }
    if (!/[A-Z]/.test(password)) {
      errors.push('대문자를 포함해주세요');
    }
    if (!/[0-9]/.test(password)) {
      errors.push('숫자를 포함해주세요');
    }
    if (!/[!@#$%^&*]/.test(password)) {
      errors.push('특수문자를 포함해주세요');
    }
  }
  
  return errors;
}

export async function signUp(formData: FormData) {
  'use server';
  
  const email = formData.get('email') as string;
  const password = formData.get('password') as string;
  
  const emailErrors = validateEmail(email);
  const passwordErrors = validatePassword(password);
  
  if (emailErrors.length > 0 || passwordErrors.length > 0) {
    return {
      success: false,
      errors: {
        email: emailErrors,
        password: passwordErrors
      }
    };
  }
  
  // 검증 통과!
  return { success: true };
}

async function checkEmailExists(email: string): Promise {
  const existing = await db.user.findUnique({
    where: { email },
    select: { id: true }
  });
  return !!existing;
}

export async function registerUser(formData: FormData) {
  'use server';
  
  const email = formData.get('email') as string;
  
  // 1단계: 기본 포맷 검증
  if (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
    return { 
      success: false, 
      error: '올바른 이메일을 입력해주세요' 
    };
  }
  
  // 2단계: DB 중복 체크
  const exists = await checkEmailExists(email);
  if (exists) {
    return { 
      success: false, 
      error: '이미 사용 중인 이메일이에요' 
    };
  }
  
  // 검증 완료!
  return { success: true };
}

비동기 검증은 시간이 걸려요. 그래서 사용자에게 로딩 상태를 보여주는 게 좋아요. useFormStatus 훅을 사용하면 쉽게 구현할 수 있어요.

const orderSchema = z.object({
  deliveryMethod: z.enum(['delivery', 'pickup']),
  address: z.string().optional(),
  age: z.number(),
  parentConsent: z.boolean().optional()
}).refine(data => {
  // 배송이면 주소 필수
  if (data.deliveryMethod === 'delivery' && !data.address) {
    return false;
  }
  return true;
}, {
  message: '배송 주소를 입력해주세요',
  path: ['address']
}).refine(data => {
  // 미성년자면 보호자 동의 필수
  if (data.age < 19 && !data.parentConsent) {
    return false;
  }
  return true;
}, {
  message: '보호자 동의가 필요해요',
  path: ['parentConsent']
});

'use server'

export async function submitForm(formData: FormData) {
  try {
    const name = formData.get('name') as string
    const email = formData.get('email') as string
    
    // 기본 검증
    if (!name || name.length < 2) {
      return {
        success: false,
        error: '이름은 최소 2자 이상이어야 해요'
      }
    }
    
    // 데이터베이스 작업
    const result = await db.user.create({
      data: { name, email }
    })
    
    return {
      success: true,
      data: result
    }
    
  } catch (error) {
    console.error('Form submission error:', error)
    
    return {
      success: false,
      error: '처리 중 문제가 발생했어요. 다시 시도해주세요.'
    }
  }
}

'use server'

import { z } from 'zod'

const formSchema = z.object({
  name: z.string()
    .min(2, '이름은 최소 2자 이상이어야 해요')
    .max(50, '이름은 50자를 넘을 수 없어요'),
  email: z.string()
    .email('올바른 이메일 형식이 아니에요'),
  age: z.number()
    .min(18, '만 18세 이상만 가입할 수 있어요')
    .max(120, '나이를 다시 확인해주세요')
})

export async function submitForm(formData: FormData) {
  const rawData = {
    name: formData.get('name'),
    email: formData.get('email'),
    age: Number(formData.get('age'))
  }
  
  // Zod 검증
  const result = formSchema.safeParse(rawData)
  
  if (!result.success) {
    // 필드별 에러 메시지 추출
    const fieldErrors = result.error.flatten().fieldErrors
    
    return {
      success: false,
      errors: fieldErrors
    }
  }
  
  // 검증 통과 후 처리
  try {
    const data = await db.user.create({
      data: result.data
    })
    
    return { success: true, data }
  } catch (error) {
    return {
      success: false,
      error: '서버 오류가 발생했어요'
    }
  }
}

'use client'

import { useFormState } from 'react-dom'
import { submitForm } from './actions'

export default function MyForm() {
  const [state, formAction] = useFormState(submitForm, null)
  
  return (
    <form action={formAction}>
      <div>
        <input 
          type="text" 
          name="name"
          className="border rounded px-3 py-2"
        />
        {state?.errors?.name && (
          <p className="text-red-500 text-sm mt-1">
            {state.errors.name[0]}
          </p>
        )}
      </div>
      
      <div>
        <input 
          type="email" 
          name="email"
          className="border rounded px-3 py-2"
        />
        {state?.errors?.email && (
          <p className="text-red-500 text-sm mt-1">
            {state.errors.email[0]}
          </p>
        )}
      </div>
      
      {state?.error && (
        <div className="bg-red-50 border border-red-200 text-red-700 px-4 py-3 rounded">
          {state.error}
        </div>
      )}
      
      <button type="submit">제출하기</button>
    </form>
  )
}

'use server'

import { PrismaClientKnownRequestError } from '@prisma/client/runtime/library'

export async function createUser(formData: FormData) {
  try {
    const email = formData.get('email') as string
    
    const user = await db.user.create({
      data: { email, name: formData.get('name') as string }
    })
    
    return { success: true, data: user }
    
  } catch (error) {
    // Prisma 에러인 경우
    if (error instanceof PrismaClientKnownRequestError) {
      // 중복 키 에러 (P2002)
      if (error.code === 'P2002') {
        const field = error.meta?.target as string[]
        return {
          success: false,
          error: `이미 사용 중인 ${field[0]}이에요`
        }
      }
      
      // 외래 키 제약 위반 (P2003)
      if (error.code === 'P2003') {
        return {
          success: false,
          error: '연결된 데이터를 찾을 수 없어요'
        }
      }
    }
    
    // 기타 에러
    console.error('Unexpected error:', error)
    return {
      success: false,
      error: '문제가 발생했어요. 잠시 후 다시 시도해주세요'
    }
  }
}

에러 메시지에 너무 많은 기술적 정보를 담지 마세요. 해커가 시스템 구조를 파악할 수 있거든요. "데이터베이스 연결 실패: localhost:5432" 이런 식의 메시지는 절대 안 돼요!

'use client'

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // 에러 로깅 서비스로 전송
    console.error('Error boundary caught:', error)
  }, [error])

  return (
    <div className="min-h-screen flex items-center justify-center">
      <div className="text-center">
        <h2 className="text-2xl font-bold mb-4">
          앗, 문제가 발생했어요!
        </h2>
        <p className="text-gray-600 mb-6">
          예상치 못한 오류가 발생했어요. 다시 시도해주세요.
        </p>
        <button
          onClick={reset}
          className="bg-indigo-600 text-white px-6 py-2 rounded-lg"
        >
          다시 시도하기
        </button>
      </div>
    </div>
  )
}

'use client';

import { useOptimistic } from 'react';
import { likePost } from './actions';

export default function LikeButton({ postId, initialLikes }) {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (state, newLike) => state + newLike
  );

  async function handleLike(formData) {
    // UI 먼저 업데이트 (낙관적)
    addOptimisticLike(1);
    
    // 실제 서버 액션 실행
    await likePost(formData);
  }

  return (
    <form action={handleLike}>
      <input type="hidden" name="postId" value={postId} />
      <button type="submit">
        ? 좋아요 ({optimisticLikes})
      </button>
    </form>
  );
}

'use server';

import { cookies } from 'next/headers';

// 스텝별 데이터를 세션에 저장
export async function saveStepData(formData) {
  const step = formData.get('step');
  const data = Object.fromEntries(formData);
  
  const cookieStore = await cookies();
  const existingData = cookieStore.get('signup_data')?.value || '{}';
  const stepData = JSON.parse(existingData);
  
  // 현재 스텝 데이터 병합
  stepData[step] = data;
  
  cookieStore.set('signup_data', JSON.stringify(stepData), {
    httpOnly: true,
    secure: true,
    maxAge: 3600 // 1시간
  });
  
  return { success: true, nextStep: parseInt(step) + 1 };
}

// 최종 제출
export async function submitMultiStepForm() {
  const cookieStore = await cookies();
  const allData = JSON.parse(
    cookieStore.get('signup_data')?.value || '{}'
  );
  
  // 모든 스텝 데이터 검증
  if (!validateAllSteps(allData)) {
    return { error: '일부 단계의 데이터가 유효하지 않아요' };
  }
  
  // DB 저장 로직
  await saveToDatabase(allData);
  
  // 세션 정리
  cookieStore.delete('signup_data');
  
  return { success: true };
}

'use server';

import { S3Client } from '@aws-sdk/client-s3';
import { createPresignedPost } from '@aws-sdk/s3-presigned-post';

// presigned URL 생성
export async function getUploadUrl(filename, fileType) {
  const s3Client = new S3Client({ region: 'ap-northeast-2' });
  
  const { url, fields } = await createPresignedPost(s3Client, {
    Bucket: process.env.S3_BUCKET,
    Key: `uploads/${Date.now()}-${filename}`,
    Conditions: [
      ['content-length-range', 0, 10485760], // 10MB
      ['starts-with', '$Content-Type', fileType],
    ],
    Expires: 600, // 10분
  });
  
  return { url, fields };
}

// 업로드 완료 후 메타데이터 저장
export async function saveFileMetadata(formData) {
  const fileUrl = formData.get('fileUrl');
  const filename = formData.get('filename');
  
  await db.files.create({
    data: {
      url: fileUrl,
      filename: filename,
      uploadedAt: new Date(),
    }
  });
  
  return { success: true };
}

'use server';

// Promise.allSettled로 안전한 병렬 처리
export async function bulkUpdateUsers(formData) {
  const userIds = formData.getAll('userId');
  const newStatus = formData.get('status');
  
  const results = await Promise.allSettled(
    userIds.map(async (userId) => {
      return await db.user.update({
        where: { id: userId },
        data: { status: newStatus }
      });
    })
  );
  
  // 성공/실패 분류
  const successful = results.filter(r => r.status === 'fulfilled').length;
  const failed = results.filter(r => r.status === 'rejected').length;
  
  return {
    success: true,
    message: `${successful}명 성공, ${failed}명 실패`,
    details: results
  };
}

// 배치 처리 (대량 데이터용)
export async function batchProcessData(formData) {
  const allData = JSON.parse(formData.get('data'));
  const BATCH_SIZE = 50;
  
  for (let i = 0; i < allData.length; i += BATCH_SIZE) {
    const batch = allData.slice(i, i + BATCH_SIZE);
    
    await Promise.all(
      batch.map(item => processItem(item))
    );
    
    // 배치 간 잠깐 쉬어가기 (DB 부하 분산)
    await new Promise(resolve => setTimeout(resolve, 100));
  }
  
  return { success: true, processed: allData.length };
}

'use server';

import { v4 as uuidv4 } from 'uuid';

// 멱등성 키를 사용한 서버 액션
export async function createOrderIdempotent(formData) {
  const idempotencyKey = formData.get('idempotencyKey') || uuidv4();
  
  // 이미 처리된 요청인지 확인
  const existing = await db.processedRequests.findUnique({
    where: { idempotencyKey }
  });
  
  if (existing) {
    return existing.result; // 기존 결과 반환
  }
  
  try {
    // 실제 주문 처리
    const order = await db.order.create({
      data: {
        userId: formData.get('userId'),
        amount: parseInt(formData.get('amount')),
        // ...
      }
    });
    
    // 처리 결과 저장 (24시간 보관)
    await db.processedRequests.create({
      data: {
        idempotencyKey,
        result: { orderId: order.id },
        expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000)
      }
    });
    
    return { success: true, orderId: order.id };
  } catch (error) {
    return { error: '주문 처리 실패' };
  }
}

// 클라이언트 재시도 로직
async function submitWithRetry(formData, maxRetries = 3) {
  let lastError;
  
  for (let i = 0; i < maxRetries; i++) {
    try {
      const result = await createOrderIdempotent(formData);
      if (result.success) return result;
      
      lastError = result.error;
    } catch (error) {
      lastError = error;
      // 지수 백오프 (1초, 2초, 4초)
      await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
    }
  }
  
  throw lastError;
}

'use client';

import { useState, useEffect } from 'react';
import { checkUsernameAvailability } from './actions';

export default function UsernameInput() {
  const [username, setUsername] = useState('');
  const [isChecking, setIsChecking] = useState(false);
  const [isAvailable, setIsAvailable] = useState(null);

  useEffect(() => {
    if (username.length < 3) return;

    setIsChecking(true);
    
    // 디바운싱: 500ms 후에 검증
    const timeoutId = setTimeout(async () => {
      const formData = new FormData();
      formData.append('username', username);
      
      const result = await checkUsernameAvailability(formData);
      setIsAvailable(result.available);
      setIsChecking(false);
    }, 500);

    return () => clearTimeout(timeoutId);
  }, [username]);

  return (
    <div>
      <input
        value={username}
        onChange={(e) => setUsername(e.target.value)}
        placeholder="사용자명 입력"
      />
      {isChecking && <span>확인 중...</span>}
      {isAvailable === true && <span>✅ 사용 가능</span>}
      {isAvailable === false && <span>❌ 이미 사용 중</span>}
    </div>
  );
}

디바운싱 시간을 너무 짧게 설정하면 서버 부하가 크고, 너무 길게 하면 사용자가 답답해해요. 보통 300~500ms 정도가 적당하더라고요. 그리고 네트워크 상태에 따라 동적으로 조절하는 것도 좋은 방법이에요.

• 항상 입력값 검증하기 - 클라이언트 검증만 믿으면 안 돼요
• 민감한 데이터는 반환하지 않기 - 비밀번호 해시 같은 거요
• 인증 상태 확인 - 매 서버 액션마다 체크하세요
• CSRF 보호 - Next.js가 자동으로 해주지만 확인은 필수!
• Rate Limiting 적용 - 무한 요청 공격 막기

'use server'

import { auth } from '@/auth'
import { rateLimit } from '@/lib/rate-limit'

export async function updateProfile(formData: FormData) {
  // 1. 인증 확인
  const session = await auth()
  if (!session) {
    return { error: '로그인이 필요합니다' }
  }

  // 2. Rate Limiting
  const rateLimitResult = await rateLimit(session.user.id)
  if (!rateLimitResult.success) {
    return { error: '너무 많은 요청이 발생했습니다' }
  }

  // 3. 권한 확인
  const userId = formData.get('userId')
  if (session.user.id !== userId) {
    return { error: '권한이 없습니다' }
  }

  // 4. 입력값 검증 (서버 측)
  const name = formData.get('name')
  if (typeof name !== 'string' || name.length < 2) {
    return { error: '이름은 2글자 이상이어야 합니다' }
  }

  // 5. 안전하게 처리
  // ...
}

낙관적 업데이트는 서버 응답을 기다리지 않고 UI를 먼저 업데이트하는 거예요. 사용자 입장에선 엄청 빠르게 느껴지죠.

'use client'

import { useOptimistic } from 'react'
import { likePost } from './actions'

export function LikeButton({ postId, initialLikes }) {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (state, newLike) => state + newLike
  )

  async function handleLike() {
    // 즉시 UI 업데이트
    addOptimisticLike(1)
    
    // 실제 서버 액션 실행
    await likePost(postId)
  }

  return (
    <button onClick={handleLike}>
      좋아요 {optimisticLikes}
    </button>
  )
}

app/
├── actions/
│   ├── auth/
│   │   ├── login.ts
│   │   └── register.ts
│   ├── posts/
│   │   ├── create.ts
│   │   ├── update.ts
│   │   └── delete.ts
│   └── index.ts (모든 액션 export)
├── lib/
│   ├── validations/
│   │   ├── auth.ts (Zod 스키마)
│   │   └── post.ts
│   └── db.ts
└── components/
    └── forms/
        ├── LoginForm.tsx
        └── PostForm.tsx

'use server'

export async function createPost(formData: FormData) {
  try {
    // 검증 에러 (사용자가 고칠 수 있음)
    const validated = postSchema.safeParse({
      title: formData.get('title'),
      content: formData.get('content')
    })

    if (!validated.success) {
      return {
        success: false,
        errors: validated.error.flatten().fieldErrors,
        message: '입력값을 확인해주세요'
      }
    }

    // DB 작업
    const post = await db.post.create({
      data: validated.data
    })

    revalidatePath('/posts')
    
    return {
      success: true,
      data: post,
      message: '게시글이 작성되었습니다'
    }

  } catch (error) {
    // 시스템 에러 (개발자가 확인해야 함)
    console.error('Post creation failed:', error)
    
    return {
      success: false,
      message: '일시적인 오류가 발생했습니다. 잠시 후 다시 시도해주세요'
    }
  }
}

// types/actions.ts
export type ActionResult<T = void> = {
  success: boolean
  data?: T
  errors?: Record<string, string[]>
  message?: string
}

// actions/posts/create.ts
'use server'

import { ActionResult } from '@/types/actions'
import { Post } from '@prisma/client'

export async function createPost(
  formData: FormData
): Promise<ActionResult<Post>> {
  // 구현...
}

// 클라이언트에서 사용
'use client'

export function PostForm() {
  async function handleSubmit(formData: FormData) {
    const result = await createPost(formData)
    
    if (result.success) {
      // result.data는 Post 타입으로 추론됨
      console.log(result.data?.title)
    }
  }
}

// lib/action-wrapper.ts
import { z } from 'zod'
import { ActionResult } from '@/types/actions'

export function createAction<T extends z.ZodType>(
  schema: T,
  handler: (data: z.infer<T>) => Promise<any>
) {
  return async (formData: FormData): Promise<ActionResult> => {
    try {
      // 1. 자동 검증
      const validated = schema.safeParse(
        Object.fromEntries(formData)
      )

      if (!validated.success) {
        return {
          success: false,
          errors: validated.error.flatten().fieldErrors
        }
      }

      // 2. 핸들러 실행
      const result = await handler(validated.data)

      return {
        success: true,
        data: result
      }
    } catch (error) {
      console.error(error)
      return {
        success: false,
        message: '오류가 발생했습니다'
      }
    }
  }
}

// 사용 예시
'use server'

export const createPost = createAction(
  postSchema,
  async (data) => {
    return await db.post.create({ data })
  }
)

• ✓ 모든 입력값을 서버에서 재검증하고 있나요?
• ✓ 에러 메시지가 사용자 친화적인가요?
• ✓ 로딩 상태를 명확하게 표시하고 있나요?
• ✓ 캐시 무효화를 적절히 하고 있나요?
• ✓ 타입 안정성이 확보되어 있나요?
• ✓ 민감한 데이터를 클라이언트에 노출하지 않나요?
• ✓ Rate Limiting이 적용되어 있나요?