피드로 돌아가기
Dev.toFrontend
원문 읽기
Zod와 Discriminated Union 기반의 Next.js Type-Safe API Layer 설계
Building a Type-Safe API Layer in Next.js App Router With Zod and Server Actions
AI 요약
Context
Next.js Server Actions의 단순한 인터페이스가 야기하는 런타임 타입 불일치와 파편화된 에러 핸들링 문제 분석. 클라이언트와 서버 간 경계에서 FormData의 불확실한 타입으로 인한 런타임 버그 발생 가능성 확인.
Technical Solution
- Discriminated Union 구조의 ActionResult 타입을 정의하여 성공과 실패 케이스에 대한 엄격한 타입 구분 설계
- Zod Schema를 통한 런타임 데이터 검증 단계 구축으로 비즈니스 로직 진입 전 입력값 무결성 보장
- safeParse 메서드를 활용하여 예외 처리 비용을 최소화하고 fieldErrors를 통해 세밀한 유효성 검사 결과 전달
- useTransition 훅과 custom hook을 결합하여 비동기 상태 관리 및 서버 응답의 타입 안정성 확보
- JSON-serializable 타입으로 입력 제한을 두어 서버-클라이언트 간 직렬화 과정의 데이터 손실 방지
- revalidatePath를 통한 데이터 변경 후 서버 캐시 갱신 전략 적용으로 상태 동기화 구현
실천 포인트
1. Server Action 응답 타입을 { success: boolean, data?: T, error?: string } 형태의 공통 인터페이스로 표준화했는가?
2. TypeScript의 타입 캐스팅(as string) 대신 Zod의 safeParse를 통한 런타임 검증을 수행하는가?
3. 서버 액션 입력값으로 클래스 인스턴스나 함수 등 직렬화 불가능한 객체를 전달하고 있지는 않은가?
4. mutation 수행 후 revalidatePath 또는 revalidateTag를 통해 적절한 캐시 무효화 전략을 세웠는가?