Next.js 서버 액션 장애 복구 플레이북: 실패를 사용자 이탈로 번지지 않게 막는 실무 설계

서버 액션을 처음 크게 썼을 때, 팀이 가장 많이 한 말은 “코드가 진짜 짧아졌다”였습니다. 문제는 배포 다음 주에 바로 나왔습니다. 주문 수정 버튼을 두 번 빠르게 누른 사용자들만 간헐적으로 실패했고, 화면에는 동일한 토스트만 반복됐습니다. 겉보기엔 작은 UX 버그였지만, 내부에서는 입력 검증 실패와 외부 결제 API 타임아웃이 같은 오류 흐름으로 처리되고 있었습니다. 사용자 입장에서는 왜 실패했는지 모르고, 운영 입장에서는 어디서부터 복구해야 할지 모르는 상태였죠. 이때 깨달은 건 단순합니다. 서버 액션의 핵심은 코드 줄이기가 아니라 실패를 읽기 쉽게 분해하는 설계라는 점입니다.

지금은 실패를 네 가지로 먼저 나눕니다. 입력 오류, 권한/세션 오류, 도메인 규칙 위반, 인프라/외부 의존성 장애. 이 분류를 강제하면 회의가 짧아집니다. 예를 들어 세션 만료는 “다시 시도해 보세요”가 아니라 재인증으로 바로 보내야 하고, 중복 요청은 멱등 키 검사에서 잘려야 합니다. 반대로 외부 API 5xx는 재시도 정책이 없으면 사용자 클릭이 장애를 증폭시키는 방향으로 흘러갑니다. 같은 실패를 누군가는 프론트 문제, 누군가는 백엔드 문제로 부르던 혼선이 줄어든 것도 이 분류 덕분이었습니다.

실행 절차는 검증 -> 실행 -> 복구로 고정했습니다. 검증 단계에서는 zod로 입력 파싱을 통일하고, 사용자 메시지와 내부 로그 코드를 분리합니다. 실행 단계에서는 request id를 먼저 만들고 DB 쓰기 전에 멱등 키를 확인합니다. 복구 단계에서는 오류를 retryable과 non-retryable로 나눠 처리합니다. 전자는 짧은 지수 백오프 재시도, 후자는 즉시 대체 경로 안내와 운영 알림으로 보냅니다. 특히 “일부만 반영된 실패”를 따로 관리해야 야간 장애 때 버틸 수 있습니다. 저희는 보상 트랜잭션 문서를 따로 두고, 온콜이 10분 안에 따라갈 수 있게 절차를 짧게 유지합니다.

배포 전 점검은 화려할 필요가 없습니다. 액션별 필수 로그 필드(requestId, userId, actionName, errorCode, latencyMs) 누락 여부만 먼저 보고, 스테이징에서 실패 시나리오 세 개를 강제로 태웁니다. 배포 후 1시간은 성공률보다 p95 지연, 재시도 비율, 동일 사용자 반복 실패를 우선 봅니다. 실제로 사용자 이탈은 이 지표에서 먼저 보였습니다. 주간 회고에서는 실패율 하나로 끝내지 않고 MTTR, 첫 재시도 성공률, 수동 개입 건수를 같이 봅니다. 이 세 개를 같이 보니 “무엇을 고쳐야 다음 주가 편해지는지”가 훨씬 선명해졌습니다.

주의할 점도 있습니다. 에러 문구를 과하게 친절하게 쓰면 내부 구조가 노출되고, 너무 추상적으로 쓰면 사용자가 같은 버튼만 반복 누릅니다. 재시도 정책을 화면마다 다르게 두는 것도 체감 품질을 망칩니다. 그래서 저희는 “실패해도 다음 행동이 분명해야 한다”를 공통 기준으로 잡고, 문구/재시도/대체 경로를 화면별로 흩어지지 않게 관리합니다. 서버 액션은 편의 기능이 아니라 트랜잭션 경계라는 관점을 팀에서 공유하면, 장애가 나도 서비스 전체 신뢰도는 덜 흔들립니다.