Next.js 14 서버 액션: 폼 처리 모범 사례 마스터하기

Next.js 14는 성능이 뛰어나고 사용자 친화적인 웹 애플리케이션을 구축하기 위한 강력한 기능들을 선보입니다. 그중에서도 서버 액션(Server Actions)은 서버에서 직접 폼 제출 및 데이터 변경(mutation)을 처리하는 혁신적인 방식으로 돋보입니다. 이 가이드는 Next.js 14의 서버 액션에 대한 포괄적인 개요를 제공하며, 폼 처리, 데이터 유효성 검사, 보안 및 고급 기술에 대한 모범 사례에 중점을 둡니다. 실용적인 예제를 살펴보고 견고하고 확장 가능한 웹 애플리케이션을 구축하는 데 도움이 되는 실행 가능한 통찰력을 제공할 것입니다.

Next.js 서버 액션이란 무엇인가요?

서버 액션은 서버에서 실행되며 React 컴포넌트에서 직접 호출할 수 있는 비동기 함수입니다. 이를 통해 폼 제출 및 데이터 변경을 처리하기 위한 기존의 API 라우트가 필요 없어져 코드가 단순화되고 보안이 향상되며 성능이 개선됩니다. 서버 액션은 React 서버 컴포넌트(RSC)이므로 서버에서 실행되어 초기 페이지 로드 속도를 높이고 SEO를 개선합니다.

서버 액션의 주요 이점:

• 단순화된 코드: 별도의 API 라우트가 필요 없어 상용구 코드를 줄입니다.
• 향상된 보안: 서버 측 실행으로 클라이언트 측 취약점을 최소화합니다.
• 개선된 성능: 서버에서 직접 데이터 변경을 실행하여 응답 시간을 단축합니다.
• 최적화된 SEO: 서버 측 렌더링을 활용하여 더 나은 검색 엔진 인덱싱을 지원합니다.
• 타입 안정성: TypeScript를 사용하여 종단 간 타입 안정성을 보장받습니다.

Next.js 14 프로젝트 설정하기

서버 액션을 시작하기 전에 Next.js 14 프로젝트가 설정되어 있는지 확인하세요. 처음부터 시작하는 경우 다음 명령을 사용하여 새 프로젝트를 생성합니다:

npx create-next-app@latest my-next-app

서버 컴포넌트와 액션을 최대한 활용하려면 프로젝트가 app 디렉토리 구조를 사용하고 있는지 확인하세요.

서버 액션을 사용한 기본 폼 처리

간단한 예제로 시작하겠습니다: 데이터베이스에 새 항목을 생성하기 위해 데이터를 제출하는 폼입니다. 입력 필드와 제출 버튼이 있는 간단한 폼을 사용하겠습니다.

예제: 새 아이템 생성하기

먼저 React 컴포넌트 내에 서버 액션 함수를 정의합니다. 이 함수는 서버에서 폼 제출 로직을 처리합니다.

// app/components/CreateItemForm.tsx
'use client';

import { useState } from 'react';

async function createItem(formData: FormData) {
  'use server'

  const name = formData.get('name') as string;

  // 데이터베이스 상호작용 시뮬레이션
  console.log('아이템 생성 중:', name);

  await new Promise((resolve) => setTimeout(resolve, 1000)); // 지연 시간 시뮬레이션

  console.log('아이템이 성공적으로 생성되었습니다!');
}

export default function CreateItemForm() {
  const [isSubmitting, setIsSubmitting] = useState(false);
  
  async function handleSubmit(formData: FormData) {
    setIsSubmitting(true);
    await createItem(formData);
    setIsSubmitting(false);
  }

  return (
    

      아이템 이름:
      
      
        {isSubmitting ? '생성 중...' : '아이템 생성'}
      
    
  );
}

설명:

• 'use client' 지시문은 이것이 클라이언트 컴포넌트임을 나타냅니다.
• createItem 함수는 'use server' 지시문으로 표시되어 서버 액션임을 나타냅니다.
• handleSubmit 함수는 서버 액션을 호출하는 클라이언트 측 함수입니다. 또한 제출 중에 버튼을 비활성화하는 것과 같은 UI 상태를 처리합니다.
• <form> 요소의 action 속성은 handleSubmit 함수로 설정됩니다.
• formData.get('name') 메서드는 'name' 입력 필드의 값을 검색합니다.
• await new Promise는 데이터베이스 작업을 시뮬레이션하고 지연 시간을 추가합니다.

데이터 유효성 검사

데이터 유효성 검사는 데이터 무결성을 보장하고 보안 취약점을 예방하는 데 중요합니다. 서버 액션은 서버 측 유효성 검사를 수행할 좋은 기회를 제공합니다. 이 접근 방식은 클라이언트 측 유효성 검사만으로는 해결할 수 없는 위험을 완화하는 데 도움이 됩니다.

예제: 입력 데이터 유효성 검사

createItem 서버 액션을 수정하여 유효성 검사 로직을 포함시킵니다.

// app/components/CreateItemForm.tsx
'use client';

import { useState } from 'react';

async function createItem(formData: FormData) {
  'use server'

  const name = formData.get('name') as string;

  if (!name || name.length < 3) {
    throw new Error('아이템 이름은 3자 이상이어야 합니다.');
  }

  // 데이터베이스 상호작용 시뮬레이션
  console.log('아이템 생성 중:', name);

  await new Promise((resolve) => setTimeout(resolve, 1000)); // 지연 시간 시뮬레이션

  console.log('아이템이 성공적으로 생성되었습니다!');
}

export default function CreateItemForm() {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [errorMessage, setErrorMessage] = useState(null);
  
  async function handleSubmit(formData: FormData) {
    setIsSubmitting(true);
    setErrorMessage(null);
    try {
      await createItem(formData);
    } catch (error: any) {
      setErrorMessage(error.message || '오류가 발생했습니다.');
    } finally {
      setIsSubmitting(false);
    }
  }

  return (
    

      

        아이템 이름:
        
        
          {isSubmitting ? '생성 중...' : '아이템 생성'}
        
      
      {errorMessage && 
{errorMessage}
}
    
  );
}

설명:

• 이제 createItem 함수는 name이 유효한지(최소 3자 이상) 확인합니다.
• 유효성 검사에 실패하면 오류가 발생합니다.
• handleSubmit 함수는 서버 액션에서 발생한 오류를 포착하여 사용자에게 오류 메시지를 표시하도록 업데이트되었습니다.

유효성 검사 라이브러리 사용하기

더 복잡한 유효성 검사 시나리오의 경우 다음과 같은 유효성 검사 라이브러리를 사용하는 것을 고려해 보세요:

• Zod: TypeScript 우선의 스키마 선언 및 유효성 검사 라이브러리입니다.
• Yup: 값의 파싱, 유효성 검사 및 변환을 위한 JavaScript 스키마 빌더입니다.

다음은 Zod를 사용한 예제입니다:

// app/utils/validation.ts
import { z } from 'zod';

export const CreateItemSchema = z.object({
  name: z.string().min(3, '아이템 이름은 3자 이상이어야 합니다.'),
});

// app/components/CreateItemForm.tsx
'use client';

import { useState } from 'react';
import { CreateItemSchema } from '../utils/validation';

async function createItem(formData: FormData) {
  'use server'

  const name = formData.get('name') as string;

  const validatedFields = CreateItemSchema.safeParse({ name });

  if (!validatedFields.success) {
    return { errors: validatedFields.error.flatten().fieldErrors };
  }

  // 데이터베이스 상호작용 시뮬레이션
  console.log('아이템 생성 중:', name);

  await new Promise((resolve) => setTimeout(resolve, 1000)); // 지연 시간 시뮬레이션

  console.log('아이템이 성공적으로 생성되었습니다!');
}

export default function CreateItemForm() {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [errorMessage, setErrorMessage] = useState(null);
  
  async function handleSubmit(formData: FormData) {
    setIsSubmitting(true);
    setErrorMessage(null);
    try {
      await createItem(formData);
    } catch (error: any) {
      setErrorMessage(error.message || '오류가 발생했습니다.');
    } finally {
      setIsSubmitting(false);
    }
  }

  return (
    

      

        아이템 이름:
        
        
          {isSubmitting ? '생성 중...' : '아이템 생성'}
        
      
      {errorMessage && 
{errorMessage}
}
    
  );
}

설명:

• CreateItemSchema는 Zod를 사용하여 name 필드에 대한 유효성 검사 규칙을 정의합니다.
• safeParse 메서드는 입력 데이터의 유효성을 검사하려고 시도합니다. 유효성 검사에 실패하면 오류가 포함된 객체를 반환합니다.
• errors 객체에는 유효성 검사 실패에 대한 자세한 정보가 포함되어 있습니다.

보안 고려 사항

서버 액션은 서버에서 코드를 실행하여 보안을 강화하지만, 일반적인 위협으로부터 애플리케이션을 보호하기 위해 보안 모범 사례를 따르는 것이 여전히 중요합니다.

사이트 간 요청 위조(CSRF) 방지

CSRF 공격은 웹사이트가 사용자 브라우저를 신뢰한다는 점을 악용합니다. CSRF 공격을 방지하려면 CSRF 보호 메커니즘을 구현해야 합니다.

Next.js는 서버 액션을 사용할 때 CSRF 보호를 자동으로 처리합니다. 프레임워크는 각 폼 제출에 대해 CSRF 토큰을 생성하고 검증하여 요청이 애플리케이션에서 비롯되었는지 확인합니다.

사용자 인증 및 권한 부여 처리

승인된 사용자만 특정 작업을 수행할 수 있도록 하세요. 중요한 데이터와 기능을 보호하기 위해 인증 및 권한 부여 메커니즘을 구현하세요.

다음은 NextAuth.js를 사용하여 서버 액션을 보호하는 예제입니다:

// app/components/CreateItemForm.tsx
'use client';

import { useState } from 'react';
import { getServerSession } from 'next-auth';
import { authOptions } from '../../app/api/auth/[...nextauth]/route';

async function createItem(formData: FormData) {
  'use server'

  const session = await getServerSession(authOptions);

  if (!session) {
    throw new Error('인증되지 않음');
  }

  const name = formData.get('name') as string;

  // 데이터베이스 상호작용 시뮬레이션
  console.log('아이템 생성 중:', name, '사용자:', session.user?.email);

  await new Promise((resolve) => setTimeout(resolve, 1000)); // 지연 시간 시뮬레이션

  console.log('아이템이 성공적으로 생성되었습니다!');
}

export default function CreateItemForm() {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [errorMessage, setErrorMessage] = useState(null);
  
  async function handleSubmit(formData: FormData) {
    setIsSubmitting(true);
    setErrorMessage(null);
    try {
      await createItem(formData);
    } catch (error: any) {
      setErrorMessage(error.message || '오류가 발생했습니다.');
    } finally {
      setIsSubmitting(false);
    }
  }

  return (
    

      

        아이템 이름:
        
        
          {isSubmitting ? '생성 중...' : '아이템 생성'}
        
      
      {errorMessage && 
{errorMessage}
}
    
  );
}

설명:

• getServerSession 함수는 사용자의 세션 정보를 검색합니다.
• 사용자가 인증되지 않은 경우(세션 없음), 오류가 발생하여 서버 액션이 실행되지 않도록 합니다.

입력 데이터 살균(Sanitizing)

사이트 간 스크립팅(XSS) 공격을 방지하기 위해 입력 데이터를 살균하세요. XSS 공격은 악성 코드가 웹사이트에 주입되어 사용자 데이터나 애플리케이션 기능을 손상시킬 수 있을 때 발생합니다.

DOMPurify 또는 sanitize-html과 같은 라이브러리를 사용하여 서버 액션에서 처리하기 전에 사용자가 제공한 입력을 살균하세요.

고급 기술

기본 사항을 다루었으므로 이제 서버 액션을 효과적으로 사용하기 위한 몇 가지 고급 기술을 살펴보겠습니다.

낙관적 업데이트(Optimistic Updates)

낙관적 업데이트는 서버가 확인하기 전에도 작업이 성공할 것처럼 UI를 즉시 업데이트하여 더 나은 사용자 경험을 제공합니다. 서버에서 작업이 실패하면 UI는 이전 상태로 되돌아갑니다.

// app/components/UpdateItemForm.tsx
'use client';

import { useState } from 'react';

async function updateItem(id: string, formData: FormData) {
  'use server'

  const name = formData.get('name') as string;

  // 데이터베이스 상호작용 시뮬레이션
  console.log('아이템 업데이트 중:', id, '이름:', name);

  await new Promise((resolve) => setTimeout(resolve, 1000)); // 지연 시간 시뮬레이션

  // 실패 시뮬레이션 (데모용)
  const shouldFail = Math.random() < 0.5;
  if (shouldFail) {
    throw new Error('아이템 업데이트에 실패했습니다.');
  }

  console.log('아이템이 성공적으로 업데이트되었습니다!');
  return { name }; // 업데이트된 이름 반환
}

export default function UpdateItemForm({ id, initialName }: { id: string; initialName: string }) {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [errorMessage, setErrorMessage] = useState(null);
  const [itemName, setItemName] = useState(initialName);

  async function handleSubmit(formData: FormData) {
    setIsSubmitting(true);
    setErrorMessage(null);

    // UI를 낙관적으로 업데이트
    const newName = formData.get('name') as string;
    setItemName(newName);

    try {
      const result = await updateItem(id, formData);
      // 성공하면 업데이트가 이미 setItemName을 통해 UI에 반영됨

    } catch (error: any) {
      setErrorMessage(error.message || '오류가 발생했습니다.');
      // 오류 발생 시 UI 되돌리기
      setItemName(initialName);
    } finally {
      setIsSubmitting(false);
    }
  }

  return (
    

      
현재 이름: {itemName}
      

        새 아이템 이름:
        
        
          {isSubmitting ? '업데이트 중...' : '아이템 업데이트'}
        
      
      {errorMessage && 
{errorMessage}
}
    
  );
}

설명:

• 서버 액션을 호출하기 전에 setItemName을 사용하여 UI가 즉시 새 아이템 이름으로 업데이트됩니다.
• 서버 액션이 실패하면 UI는 원래 아이템 이름으로 되돌아갑니다.

데이터 재검증

서버 액션이 데이터를 수정한 후에는 UI가 최신 변경 사항을 반영하도록 캐시된 데이터를 재검증해야 할 수 있습니다. Next.js는 데이터를 재검증하는 여러 가지 방법을 제공합니다:

• 경로 재검증(Revalidate Path): 특정 경로에 대한 캐시를 재검증합니다.
• 태그 재검증(Revalidate Tag): 특정 태그와 관련된 데이터에 대한 캐시를 재검증합니다.

다음은 새 아이템을 생성한 후 경로를 재검증하는 예제입니다:

// app/components/CreateItemForm.tsx
'use client';

import { useState } from 'react';
import { revalidatePath } from 'next/cache';

async function createItem(formData: FormData) {
  'use server'

  const name = formData.get('name') as string;

  // 데이터베이스 상호작용 시뮬레이션
  console.log('아이템 생성 중:', name);

  await new Promise((resolve) => setTimeout(resolve, 1000)); // 지연 시간 시뮬레이션

  console.log('아이템이 성공적으로 생성되었습니다!');

  revalidatePath('/items'); // /items 경로 재검증
}

export default function CreateItemForm() {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [errorMessage, setErrorMessage] = useState(null);
  
  async function handleSubmit(formData: FormData) {
    setIsSubmitting(true);
    setErrorMessage(null);
    try {
      await createItem(formData);
    } catch (error: any) {
      setErrorMessage(error.message || '오류가 발생했습니다.');
    } finally {
      setIsSubmitting(false);
    }
  }

  return (
    

      

        아이템 이름:
        
        
          {isSubmitting ? '생성 중...' : '아이템 생성'}
        
      
      {errorMessage && 
{errorMessage}
}
    
  );
}

설명:

• revalidatePath('/items') 함수는 /items 경로에 대한 캐시를 무효화하여 해당 경로에 대한 다음 요청이 최신 데이터를 가져오도록 보장합니다.

서버 액션 모범 사례

서버 액션의 이점을 극대화하려면 다음 모범 사례를 고려하세요:

• 서버 액션을 작고 집중적으로 유지하세요: 서버 액션은 단일하고 잘 정의된 작업을 수행해야 합니다. 가독성과 테스트 용이성을 유지하기 위해 서버 액션 내의 복잡한 로직을 피하세요.
• 설명적인 이름을 사용하세요: 서버 액션에 목적을 명확하게 나타내는 설명적인 이름을 지정하세요.
• 오류를 정상적으로 처리하세요: 사용자에게 유익한 피드백을 제공하고 애플리케이션 충돌을 방지하기 위해 강력한 오류 처리 기능을 구현하세요.
• 데이터를 철저히 검증하세요: 데이터 무결성을 보장하고 보안 취약점을 예방하기 위해 포괄적인 데이터 유효성 검사를 수행하세요.
• 서버 액션을 보호하세요: 중요한 데이터와 기능을 보호하기 위해 인증 및 권한 부여 메커니즘을 구현하세요.
• 성능을 최적화하세요: 서버 액션의 성능을 모니터링하고 필요에 따라 최적화하여 빠른 응답 시간을 보장하세요.
• 캐싱을 효과적으로 활용하세요: Next.js의 캐싱 메커니즘을 활용하여 성능을 개선하고 데이터베이스 부하를 줄이세요.

일반적인 함정과 이를 피하는 방법

서버 액션은 수많은 이점을 제공하지만, 알아두어야 할 몇 가지 일반적인 함정이 있습니다:

• 과도하게 복잡한 서버 액션: 단일 서버 액션 안에 너무 많은 로직을 넣지 마세요. 복잡한 작업을 더 작고 관리하기 쉬운 함수로 나누세요.
• 오류 처리 소홀: 예상치 못한 오류를 포착하고 사용자에게 유용한 피드백을 제공하기 위해 항상 오류 처리를 포함하세요.
• 보안 모범 사례 무시: XSS 및 CSRF와 같은 일반적인 위협으로부터 애플리케이션을 보호하기 위해 보안 모범 사례를 따르세요.
• 데이터 재검증 잊기: 서버 액션이 데이터를 수정한 후에는 UI를 최신 상태로 유지하기 위해 캐시된 데이터를 재검증해야 합니다.

결론

Next.js 14 서버 액션은 서버에서 직접 폼 제출 및 데이터 변경을 처리하는 강력하고 효율적인 방법을 제공합니다. 이 가이드에 설명된 모범 사례를 따르면 견고하고 안전하며 성능이 뛰어난 웹 애플리케이션을 구축할 수 있습니다. 서버 액션을 활용하여 코드를 단순화하고 보안을 강화하며 전반적인 사용자 경험을 개선하세요. 이러한 원칙을 통합할 때 개발 선택이 미치는 전 세계적인 영향을 고려하십시오. 폼 및 데이터 처리 프로세스가 다양한 국제 사용자들이 접근 가능하고 안전하며 사용자 친화적인지 확인하십시오. 이러한 포용성에 대한 노력은 애플리케이션의 사용성을 향상시킬 뿐만 아니라 전 세계적으로 그 범위와 효과를 넓힐 것입니다.