서버 액션
우선순위: P1 (높음)
[!WARNING] 프로젝트가 App Router 대신
pages/디렉터리를 사용하는 경우, 이 스킬을 완전히 무시하십시오.
API 엔드포인트를 생성하지 않고 폼 제출 및 변형을 처리합니다.
구현 가이드라인
-
지시어: 파일이나 함수를 항상
'use server'로 시작하십시오. 타입이 지정된 폼 필드에 접근하려면formData.get('title')을 사용하십시오. 변형을 위해 async 함수를 내보내십시오(export). -
폼 처리:
<form>의actionprop을 사용하여action={createPost}와 같이 액션을 트리거하십시오.useFormStatus()를 사용하여pending상태를 처리하고, 버튼에disabled={pending}을 적용하십시오. React 19/Next.js 15에서는useActionState를 사용하여<form action={action}>과 함께action={action}폼 상태를 처리하십시오. -
데이터 갱신: 성공적인 변형 후
revalidatePath('/')또는revalidateTag('tag-name')를 사용하여 UI를 업데이트하십시오. -
상호작용: 폼이 아닌 트리거의 경우
useTransition훅을 사용하여 액션을 호출하고 로딩 UI를 처리하며 페이지가 차단되지 않도록 하십시오. -
낙관적 업데이트:
useOptimistic을 사용하여 서버가 변형을 확인하기 전에 예상되는 UI 상태를 즉시 표시하십시오. -
보안:
FormData에서 가져온 모든 입력값을 정제하십시오. 모든 액션 내에서 인증 검사(await auth())를 수행하십시오. 파일 업로드는 크기와 MIME 유형으로 제한하십시오. -
폼:
<form action={createPost}>(점진적 향상은 JS 없이도 작동합니다). -
이벤트 핸들러:
onClick={() => createPost(data)}. -
대기 상태:
useFormStatus훅을 사용하십시오 (해당 훅은 폼 내부에 렌더링된 컴포넌트 안에 있어야 합니다).
P1: 운영 표준
1. 보안 및 유효성 검사
처리하기 전에 항상 z.object({ 스키마와 safeParse로 입력값의 유효성을 검사하십시오. 액션 내에서 권한을 확인하십시오. 보안 액션 예제를 참조하십시오.
2. 대기 상태
상태 관리를 위해 useActionState(React 19/Next.js 15+)를 사용하고 버튼 로딩 상태를 위해 useFormStatus를 사용하십시오.
제약 사항
- 클로저: 숨겨진 클로저 암호화 오버헤드와 직렬화 버그를 방지하기 위해 컴포넌트 내부에 액션을 정의하지 마십시오.
- 리디렉션: 성공적인 탐색을 위해
redirect()를 사용하십시오. 이 함수는 Next.js가 리디렉션을 처리하기 위해 잡는 예외를 던집니다.
안티 패턴
- 유효성 검사되지 않은 서버 액션 입력 금지: 처리 전에 항상 Zod를 사용하여 유효성을 검사하십시오.
- 인증 검사 생략 금지: 미들웨어뿐만 아니라 모든 액션 내에서 세션/사용자를 확인하십시오.
- 컴포넌트 내부에 액션 정의 금지: 클로저 버그를 방지하기 위해
actions.ts에 정의하십시오. - try/catch 내에서
redirect()사용 금지:redirect()는 예외를 던지므로, 이를 catch하면 리디렉션이 실행되지 않습니다.