폼 액션: 변경 작업에서 API 경로 대체하기

전통적인 Next.js 애플리케이션에서는 폼 제출에 onSubmit 처리기가 있는 클라이언트 컴포넌트가 필요하며, 이 처리기는 fetch()를 호출하여 API 경로로 데이터를 POST해야 합니다. 이 패턴은 작동하지만 클라이언트 측 데이터 요청 로직과 서버 측 경로 처리기를 별도로 작성하고 유지 관리해야 합니다.

서버 액션을 사용하면 데이터 요청 호출과 API 경로를 하나의 함수로 대체할 수 있습니다. 폼 요소는 서버 액션을 action 속성으로 받습니다: <form action={serverAction}>. 리액트는 제출을 가로채 폼 데이터와 함께 액션을 자동으로 호출합니다.

폼에서 트리거된 서버 액션은 인수로 FormData 객체를 자동으로 받습니다. formData.get('email')을 사용하면 개별 필드에 접근할 수 있으며, 이 메서드는 값을 문자열로 반환합니다. 여러 선택 항목이 있는 필드에 사용하는 getAll()을 비롯해 모든 표준 FormData 메서드를 사용할 수 있습니다.

서버 액션은 클라이언트에서 사용할 수 있는 직렬화 가능한 값을 반환할 수 있습니다. { error: 'Email already exists' }와 같은 오류 객체나 { success: true }와 같은 성공 표시를 반환하면 전체 페이지를 다시 불러오지 않고도 클라이언트가 그에 맞게 화면을 업데이트할 수 있습니다.

폼 액션이 서버 액션이므로 폼을 포함하는 페이지 컴포넌트는 클라이언트 컴포넌트일 필요가 없습니다. 서버가 폼을 정적인 HTML로 렌더링하고, 오류 표시와 같은 대화형 부분에만 클라이언트 측 JavaScript가 필요합니다. 따라서 클라이언트 번들 크기를 크게 줄일 수 있습니다.

action={serverAction}이 지정된 폼은 JavaScript가 활성화되지 않은 환경에서도 작동합니다. 브라우저는 표준 HTML 폼 POST를 수행하고, 서버는 액션을 실행한 다음 업데이트된 페이지를 반환합니다. 이러한 진정한 점진적 향상 덕분에 모든 환경에서 폼이 자연스럽게 기능을 축소하여 제공합니다.

서버 액션이 데이터를 변경한 후에는 캐시된 페이지 데이터를 새로 고쳐야 합니다. 액션 내부에서 revalidatePath('/dashboard')를 호출하면 해당 경로에 대한 Next.js 캐시가 무효화되어 다음 요청에서 최신 데이터를 가져옵니다. 이는 변경 작업 후 서버에서 렌더링되는 페이지를 최신 상태로 유지하는 표준 방법입니다.

revalidateTag('user-data')는 revalidatePath보다 더 세밀하게 캐시를 무효화합니다. next: { tags: ['user-data'] }로 데이터 요청에 태그를 지정한 다음, 어떤 경로에서 해당 데이터를 표시하는지와 관계없이 서버 액션 내부에서 태그가 지정된 모든 데이터를 한 번에 무효화할 수 있습니다.

서버 액션은 성공적인 변경 작업 후 next/navigation 모듈에서 redirect('/success')를 호출하여 사용자를 새 페이지로 이동시킬 수 있습니다. 이 리디렉션은 서버 측에서 처리되므로 브라우저는 클라이언트 측 리디렉션이 아니라 올바른 탐색 응답을 받습니다.

서버 액션은 폼 제출에만 제한되지 않습니다. 버튼 클릭이나 기타 폼 외 트리거에서는 액션 호출을 startTransition(() => action(arg))으로 감싸십시오. 이렇게 하면 탐색이 전환으로 표시되어 액션이 서버에서 실행되는 동안 리액트가 현재 화면을 계속 표시할 수 있습니다.

서버 액션은 서버 측 유효성 검사를 수행하기에 적합한 위치입니다. FormData 필드를 검사하고, 검사에 실패하면 유효성 검사 오류를 반환하며, 모든 필드가 유효할 때만 변경 작업을 진행하십시오. Zod 같은 라이브러리를 이곳에 잘 통합할 수 있습니다. FormData를 형식이 지정된 스키마로 파싱하고 실패하면 오류 맵을 반환하면 됩니다.

폼 제출로 트리거될 때 서버 액션은 인수로 무엇을 받습니까?

서버 액션은 폼 변경 작업에서 데이터 요청 + API 경로 패턴을 대체합니다. 폼의 action 속성은 서버 액션을 직접 받고, 서버 액션은 FormData 객체를 받습니다. 액션은 클라이언트 화면 업데이트에 사용할 직렬화 가능한 결과를 반환하며, 캐시 무효화를 위한 revalidatePath와 revalidateTag를 지원하고 JavaScript 없이도 점진적으로 작동합니다.