2025년 9월 1일한국어

비동기 액션으로 트리거되는 간소화된 상태 관리를 위해 React의 useActionState 훅을 알아보세요. 애플리케이션의 효율성과 사용자 경험을 향상시키세요.

React useActionState 구현: 액션 기반 상태 관리

최신 버전에 도입된 React의 useActionState 훅은 비동기 액션으로 인해 발생하는 상태 업데이트를 관리하기 위한 세련된 접근 방식을 제공합니다. 이 강력한 도구는 특히 React 서버 컴포넌트(RSC) 및 서버 액션과 함께 작업할 때 뮤테이션 처리, UI 업데이트 및 오류 상태 관리 프로세스를 간소화합니다. 이 가이드에서는 useActionState의 복잡한 부분을 탐색하고 구현을 위한 실용적인 예제와 모범 사례를 제공합니다.

액션 기반 상태 관리의 필요성 이해하기

전통적인 React 상태 관리는 종종 컴포넌트 내에서 로딩 및 오류 상태를 별도로 관리하는 것을 포함합니다. 액션(예: 폼 제출, 데이터 가져오기)이 상태 업데이트를 트리거할 때 개발자는 일반적으로 여러 useState 호출과 잠재적으로 복잡한 조건부 로직으로 이러한 상태를 관리합니다. useActionState는 더 깨끗하고 통합된 솔루션을 제공합니다.

간단한 폼 제출 시나리오를 생각해 봅시다. useActionState가 없다면 다음과 같을 수 있습니다:

폼 데이터를 위한 상태 변수.
폼이 제출 중인지(로딩 상태)를 추적하기 위한 상태 변수.
오류 메시지를 담을 상태 변수.

이 접근 방식은 코드를 장황하게 만들고 잠재적인 불일치를 유발할 수 있습니다. useActionState는 이러한 문제들을 단일 훅으로 통합하여 로직을 단순화하고 코드 가독성을 향상시킵니다.

useActionState 소개

useActionState 훅은 두 개의 인수를 받습니다:

상태 업데이트를 수행하는 비동기 함수("액션"). 이는 서버 액션 또는 모든 비동기 함수가 될 수 있습니다.
초기 상태 값.

이 훅은 두 개의 요소를 포함하는 배열을 반환합니다:

현재 상태 값.
액션을 디스패치하는 함수. 이 함수는 액션과 관련된 로딩 및 오류 상태를 자동으로 관리합니다.

기본 예시는 다음과 같습니다:


import { useActionState } from 'react';

async function updateServer(prevState, formData) {
  // 비동기 서버 업데이트를 시뮬레이션합니다.
  await new Promise(resolve => setTimeout(resolve, 1000));

  const data = Object.fromEntries(formData);

  if (data.name === "error") {
     return '서버 업데이트에 실패했습니다.';
  }

  return `이름이 ${data.name}(으)로 업데이트되었습니다`;
}

function MyComponent() {
  const [state, dispatch] = useActionState(updateServer, '초기 상태');

  async function handleSubmit(event) {
    event.preventDefault();
    const formData = new FormData(event.target);
    const result = await dispatch(formData);
    console.log(result);
  }

  return (
    
      이름:
      
      
      상태: {state}
    
  );
}

이 예시에서:

updateServer는 서버 업데이트를 시뮬레이션하는 비동기 액션입니다. 이전 상태와 폼 데이터를 받습니다.
useActionState는 상태를 '초기 상태'로 초기화하고 현재 상태와 dispatch 함수를 반환합니다.
handleSubmit 함수는 폼 데이터를 사용하여 dispatch를 호출합니다. useActionState는 액션 실행 중 로딩 및 오류 상태를 자동으로 처리합니다.

로딩 및 오류 상태 처리하기

useActionState의 주요 이점 중 하나는 로딩 및 오류 상태를 내장하여 관리한다는 점입니다. dispatch 함수는 액션의 결과로 해결되는 프로미스를 반환합니다. 액션이 오류를 던지면 프로미스는 해당 오류로 거부됩니다. 이를 사용하여 UI를 적절하게 업데이트할 수 있습니다.

이전 예제를 수정하여 로딩 메시지와 오류 메시지를 표시해 보겠습니다:


import { useActionState } from 'react';
import { useState } from 'react';

async function updateServer(prevState, formData) {
  // 비동기 서버 업데이트를 시뮬레이션합니다.
  await new Promise(resolve => setTimeout(resolve, 1000));

  const data = Object.fromEntries(formData);

  if (data.name === "error") {
     throw new Error('서버 업데이트에 실패했습니다.');
  }

  return `이름이 ${data.name}(으)로 업데이트되었습니다`;
}

function MyComponent() {
  const [state, dispatch] = useActionState(updateServer, '초기 상태');
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [errorMessage, setErrorMessage] = useState(null);

  async function handleSubmit(event) {
    event.preventDefault();
    const formData = new FormData(event.target);
    setIsSubmitting(true);
    setErrorMessage(null);

    try {
      const result = await dispatch(formData);
      console.log(result);
    } catch (error) {
      console.error("제출 중 오류 발생:", error);
      setErrorMessage(error.message);
    } finally {
      setIsSubmitting(false);
    }
  }

  return (
    
      이름:
      
      
      {isSubmitting && 로딩 중...}
      {errorMessage && 오류: {errorMessage}}
      상태: {state}
    
  );
}

주요 변경 사항:

로딩 및 오류 상태를 추적하기 위해 isSubmitting과 errorMessage 상태 변수를 추가했습니다.
handleSubmit에서 dispatch를 호출하기 전에 isSubmitting을 true로 설정하고, 오류를 잡아 errorMessage를 업데이트합니다.
제출 중에는 제출 버튼을 비활성화하고 조건부로 로딩 및 오류 메시지를 표시합니다.

React 서버 컴포넌트(RSC)에서 서버 액션과 함께 useActionState 사용하기

useActionState는 React 서버 컴포넌트(RSC) 및 서버 액션과 함께 사용할 때 빛을 발합니다. 서버 액션은 서버에서 실행되며 데이터 소스를 직접 변경할 수 있는 함수입니다. 이를 통해 API 엔드포인트를 작성하지 않고도 서버 측 작업을 수행할 수 있습니다.

참고: 이 예제는 서버 컴포넌트와 서버 액션이 구성된 React 환경이 필요합니다.


// app/actions.js (서버 액션)
'use server';

import { cookies } from 'next/headers'; // 예시, Next.js용

export async function updateName(prevState, formData) {
  const name = formData.get('name');

  if (!name) {
    return '이름을 입력해주세요.';
  }

  try {
    // 데이터베이스 업데이트를 시뮬레이션합니다.
    await new Promise(resolve => setTimeout(resolve, 1000));

    cookies().set('userName', name);

    return `이름이 ${name}(으)로 업데이트되었습니다`; // 성공!

  } catch (error) {
    console.error("데이터베이스 업데이트 실패:", error);
    return '이름 업데이트에 실패했습니다.'; // 중요: Error를 던지는 대신 메시지를 반환하세요
  }
}


// app/page.jsx (React 서버 컴포넌트)
'use client';

import { useActionState } from 'react';
import { updateName } from './actions';

function MyComponent() {
  const [state, dispatch] = useActionState(updateName, '초기 상태');

  async function handleSubmit(event) {
    event.preventDefault();
    const formData = new FormData(event.target);
    const result = await dispatch(formData);
    console.log(result);
  }

  return (
    
      이름:
      
      
      상태: {state}
    
  );
}

export default MyComponent;

이 예제에서:

updateName은 app/actions.js에 정의된 서버 액션입니다. 이전 상태와 폼 데이터를 받아 데이터베이스를 업데이트(시뮬레이션)하고 성공 또는 오류 메시지를 반환합니다. 중요한 점은, 액션이 오류를 던지는 대신 메시지를 반환한다는 것입니다. 서버 액션은 유용한 정보를 담은 메시지를 반환하는 것을 선호합니다.
컴포넌트는 useActionState 훅을 사용하기 위해 클라이언트 컴포넌트('use client')로 표시됩니다.
handleSubmit 함수는 폼 데이터를 사용하여 dispatch를 호출합니다. useActionState는 서버 액션의 결과에 따라 상태 업데이트를 자동으로 관리합니다.

서버 액션에 대한 중요 고려사항

서버 액션에서의 오류 처리: 오류를 던지는 대신 서버 액션에서 의미 있는 오류 메시지를 반환하세요. useActionState는 이 메시지를 새로운 상태로 처리합니다. 이를 통해 클라이언트에서 우아한 오류 처리가 가능합니다.
낙관적 업데이트: 서버 액션은 체감 성능을 향상시키기 위해 낙관적 업데이트와 함께 사용될 수 있습니다. UI를 즉시 업데이트하고 액션이 실패하면 되돌릴 수 있습니다.
재검증(Revalidation): 성공적인 뮤테이션 후에는 캐시된 데이터를 재검증하여 UI가 최신 상태를 반영하도록 하는 것을 고려하세요.

고급 useActionState 기법

1. 복잡한 상태 업데이트를 위한 리듀서 사용

더 복잡한 상태 로직의 경우, useActionState를 리듀서 함수와 결합할 수 있습니다. 이를 통해 예측 가능하고 유지보수 가능한 방식으로 상태 업데이트를 관리할 수 있습니다.


import { useActionState } from 'react';
import { useReducer } from 'react';

const initialState = {
  count: 0,
  message: '초기 상태',
};

function reducer(state, action) {
  switch (action.type) {
    case 'INCREMENT':
      return { ...state, count: state.count + 1 };
    case 'DECREMENT':
      return { ...state, count: state.count - 1 };
    case 'SET_MESSAGE':
      return { ...state, message: action.payload };
    default:
      return state;
  }
}

async function updateState(state, action) {
  // 비동기 작업을 시뮬레이션합니다.
  await new Promise(resolve => setTimeout(resolve, 500));

  switch (action.type) {
    case 'INCREMENT':
      return reducer(state, action);
    case 'DECREMENT':
      return reducer(state, action);
    case 'SET_MESSAGE':
      return reducer(state, action);
    default:
      return state;
  }
}

function MyComponent() {
  const [state, dispatch] = useActionState(updateState, initialState);

  return (
    
      카운트: {state.count}
      메시지: {state.message}
      
      
      
    
  );
}

2. useActionState를 사용한 낙관적 업데이트

낙관적 업데이트는 액션이 성공한 것처럼 즉시 UI를 업데이트한 다음, 액션이 실패하면 업데이트를 되돌려 사용자 경험을 향상시킵니다. 이를 통해 애플리케이션이 더 반응적으로 느껴지게 할 수 있습니다.


import { useActionState } from 'react';
import { useState } from 'react';

async function updateServer(prevState, formData) {
  // 비동기 서버 업데이트를 시뮬레이션합니다.
  await new Promise(resolve => setTimeout(resolve, 1000));

  const data = Object.fromEntries(formData);

  if (data.name === "error") {
     throw new Error('서버 업데이트에 실패했습니다.');
  }

  return `이름이 ${data.name}(으)로 업데이트되었습니다`;
}

function MyComponent() {
  const [name, setName] = useState('초기 이름');
  const [state, dispatch] = useActionState(async (prevName, newName) => {
    try {
      const result = await updateServer(prevName, {
        name: newName,
      });
      return newName; // 성공 시 업데이트
    } catch (error) {
      // 오류 발생 시 되돌리기
      console.error("업데이트 실패:", error);
      setName(prevName);
      return prevName;
    }
  }, name);

  async function handleSubmit(event) {
    event.preventDefault();
    const formData = new FormData(event.target);
    const newName = formData.get('name');
    setName(newName); // UI를 낙관적으로 업데이트
    await dispatch(newName);
  }

  return (
    
      이름:
      
      
      현재 이름: {name}
      상태: {state}
    
  );
}

3. 액션 디바운싱

어떤 시나리오에서는 액션이 너무 자주 디스패치되는 것을 방지하기 위해 디바운싱하고 싶을 수 있습니다. 이는 사용자가 특정 기간 동안 타이핑을 멈춘 후에만 액션을 트리거하려는 검색 입력과 같은 시나리오에서 유용할 수 있습니다.


import { useActionState } from 'react';
import { useState, useEffect } from 'react';

async function searchItems(prevState, query) {
  // 비동기 검색을 시뮬레이션합니다.
  await new Promise(resolve => setTimeout(resolve, 500));

  return `검색 결과: ${query}`;
}

function MyComponent() {
  const [query, setQuery] = useState('');
  const [state, dispatch] = useActionState(searchItems, '초기 상태');

  useEffect(() => {
    const timeoutId = setTimeout(() => {
      if (query) {
        dispatch(query);
      }
    }, 300); // 300ms 동안 디바운스

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

  return (
    
      검색:
       setQuery(e.target.value)}
      />
      상태: {state}
    
  );
}

useActionState를 위한 모범 사례

액션을 순수하게 유지하기: 액션이 순수 함수(또는 가능한 한 가깝게)이도록 하세요. 상태 업데이트 외의 부수 효과가 없어야 합니다.
우아하게 오류 처리하기: 항상 액션에서 오류를 처리하고 사용자에게 유용한 오류 메시지를 제공하세요. 서버 액션의 경우 위에서 언급했듯이 오류를 던지는 대신 서버 액션에서 오류 메시지 문자열을 반환하는 것을 선호합니다.
성능 최적화하기: 특히 대용량 데이터셋을 다룰 때 액션의 성능 영향을 유의하세요. 불필요한 리렌더링을 피하기 위해 메모이제이션 기법 사용을 고려하세요.
접근성 고려하기: 장애가 있는 사용자를 포함한 모든 사용자가 애플리케이션에 접근할 수 있도록 하세요. 적절한 ARIA 속성과 키보드 탐색을 제공하세요.
철저한 테스트: 단위 테스트와 통합 테스트를 작성하여 액션과 상태 업데이트가 올바르게 작동하는지 확인하세요.
국제화(i18n): 글로벌 애플리케이션의 경우, 여러 언어와 문화를 지원하기 위해 i18n을 구현하세요.
지역화(l10n): 현지화된 콘텐츠, 날짜 형식, 통화 기호를 제공하여 특정 지역에 맞게 애플리케이션을 조정하세요.

useActionState 대 다른 상태 관리 솔루션

useActionState는 액션 기반 상태 업데이트를 관리하는 편리한 방법을 제공하지만, 모든 상태 관리 솔루션을 대체하는 것은 아닙니다. 여러 컴포넌트에 걸쳐 공유되어야 하는 복잡한 전역 상태를 가진 애플리케이션의 경우, Redux, Zustand 또는 Jotai와 같은 라이브러리가 더 적합할 수 있습니다.

useActionState를 사용해야 할 때:

단순하거나 중간 복잡도의 상태 업데이트.
비동기 액션과 밀접하게 결합된 상태 업데이트.
React 서버 컴포넌트 및 서버 액션과의 통합.

다른 솔루션을 고려해야 할 때:

복잡한 전역 상태 관리.
많은 수의 컴포넌트에서 공유되어야 하는 상태.
시간 여행 디버깅이나 미들웨어와 같은 고급 기능.

결론

React의 useActionState 훅은 비동기 액션에 의해 트리거되는 상태 업데이트를 관리하는 강력하고 우아한 방법을 제공합니다. 로딩 및 오류 상태를 통합함으로써 코드를 단순화하고 가독성을 향상시키며, 특히 React 서버 컴포넌트 및 서버 액션과 함께 작업할 때 유용합니다. 그 강점과 한계를 이해하면 애플리케이션에 적합한 상태 관리 접근 방식을 선택할 수 있으며, 이는 더 유지보수하기 쉽고 효율적인 코드로 이어집니다.

이 가이드에서 설명한 모범 사례를 따르면, useActionState를 효과적으로 활용하여 애플리케이션의 사용자 경험과 개발 워크플로우를 향상시킬 수 있습니다. 애플리케이션의 복잡성을 고려하고 필요에 가장 적합한 상태 관리 솔루션을 선택하는 것을 잊지 마세요. 간단한 폼 제출부터 복잡한 데이터 뮤테이션에 이르기까지, useActionState는 React 개발 무기고에서 귀중한 도구가 될 수 있습니다.