지니로그

프론트엔드 단독 구축 후 리드

이상 데이터 한 건이 회원 목록 전체를 빈 화면으로 만들었다

기간
2025.11 – 2026.07
역할
프론트엔드 단독 구축 후 리드
사용 기술
React 19TypeScriptVite 7TanStack Router/Query/TableZodTailwind CSS v4Spring Boot

백엔드 enum 을 매핑할 때 미지값이면 throw 하도록 엄격하게 만들었는데, 그 throw 가 배열 변환 안에서 발생해 단 한 건의 이상 데이터가 회원 목록 전체를 빈 화면으로 만들었다. 매퍼를 느슨하게 고치는 대신 호출부에서 감싸 실패한 행만 격리하고 로그로 노출하도록 바꿨다. 엄격함을 유지하면서 폭발 반경만 줄인 선택이다.

무엇을 만들었나

SaaS 제품을 운영하기 위한 사내 전용 백오피스의 프론트엔드를 혼자 세우고 이후 리드했다. 회원·구독·요금제·쿠폰·매출·VoC 를 관리하고, 고객 프로젝트의 데이터를 운영자가 직접 검수·수정·승인하는 도구다.

입사 직후에는 상용 어드민 템플릿으로 4개 화면을 세팅해 기획을 먼저 검증했고, 3개월 뒤 운영 도구에 맞는 스택으로 전면 재구축했다. 라우팅·서버 상태·테이블·폼·전역 상태의 역할을 분리하고 feature 단위 모듈 구조를 확립했다.

엄격한 검증이 오히려 장애를 만든 사례였다. 엄격함은 그대로 두고 폭발 반경만 줄인 설계를 아래에 정리한다.

무엇이 문제였나

구독 상태나 결제주기에 예상 밖의 값이 한 건이라도 섞이면 회원 목록 전체가 빈 화면이 됐다. 상세 화면은 무한 로딩에 빠졌다.

한 건에 이상이 있으면 나머지 전부를 못 본다. 운영자 입장에서는 “백오피스가 죽었다”로 보인다.

왜 한 건이 전체를 죽였나

enum 매핑 함수를 “미지값이면 throw” 로 엄격하게 만들었기 때문이다.

이 결정 자체는 근거가 있었다. 백엔드 enum 을 화면 표기로 바꿀 때 모르는 값이 오면 선택지는 둘이다.

  1. 임의의 기본값으로 폴백한다 → 잘못된 정보가 조용히 화면에 표시된다. 운영자가 “월간 구독”이라고 적힌 화면을 보고 판단을 내리는데 실제로는 연간일 수 있다.
  2. 던진다 → 문제가 드러난다.

운영 도구에서 조용한 오표시는 위험하다고 판단해 2번을 택했다. 그 판단은 지금도 옳다고 생각한다.

문제는 던진 위치였다. 그 throw 가 배열 변환 안에서 발생했다.

const rows = response.items.map(toMemberRow); // 한 건이 던지면 전체가 중단된다

map 은 부분 실패라는 개념이 없다. 원소 하나가 던지면 배열 전체가 없어지고 예외가 위로 전파된다. 그 위에는 페이지 컴포넌트가 있으니 페이지가 통째로 실패한다.

엄격함의 방향은 맞았는데 폭발 반경을 설계하지 않았다.

어떻게 해결했나

매퍼를 느슨하게 만들지 않고 경계에서 감쌌다.

가장 쉬운 해결책은 매퍼가 미지값에 기본값을 반환하도록 고치는 것이다. 그러면 화면은 절대 안 죽는다. 그리고 위에서 말한 1번 문제가 그대로 돌아온다 — 잘못된 정보가 조용히 표시된다.

그래서 매퍼는 엄격한 채로 두고, 호출부에서 감싸는 안전 매핑 헬퍼를 만들었다. 원소 단위로 시도해서 실패한 것만 격리하고, 성공한 것은 그대로 통과시킨다. 실패한 행은 어떤 값이 문제였는지 컨텍스트와 함께 로그로 남긴다.

화면에서는 해당 셀만 - 로 렌더한다. 그 행의 나머지 정보는 정상적으로 보인다. 운영자는 “이 회원의 결제주기 값이 이상하다”는 것을 알 수 있고, 나머지 업무는 막히지 않는다.

정리하면 세 층이다.

층책임
매퍼모르는 값을 절대 추측하지 않는다 (엄격)
경계 헬퍼실패를 행 단위로 격리하고 로그로 드러낸다
화면실패한 셀만 축소 표기하고 나머지는 정상 렌더

“엄격하게 만들 것인가, 안 죽게 만들 것인가”는 양자택일이 아니었다. 엄격함은 매퍼에 두고 복원력은 경계에 두면 둘 다 가진다.

같은 사고방식을 도메인 전체에 적용했다

요금제 도메인을 정리하면서 같은 원칙을 문서로 명문화했다.

4개 feature 에 흩어져 중복 정의되던 플랜 티어·결제주기·쿼터 개념을 한 곳으로 통합했다. 그러면서 티어별로 분기하는 switch 에 의도적으로 default 를 두지 않았다. 새 티어가 추가되면 조용히 잘못된 분기로 흘러가는 대신 컴파일 에러가 난다.

default 를 없애는 것과 매퍼를 엄격하게 두는 것은 같은 이야기다 — 모르는 상태를 아는 척하지 않는다. 차이는 언제 드러나는가뿐이다. switch 는 컴파일 타임에, 매퍼는 런타임에 드러난다. 런타임에 드러나는 쪽은 폭발 반경 설계가 추가로 필요하다는 것을 이 사건으로 배웠다.

진입 경로에 따라 화면이 비던 문제도 같은 뿌리였다

비슷한 시기에, 특정 경로로 들어가면 상세 화면에 아무것도 안 나오는 문제가 있었다. 메뉴로 직접 들어가면 정상인데 회원 상세를 거쳐 들어가면 빈 화면이었다.

원인은 상세 조회에 필요한 식별자 두 개가 그 경로에서는 빈 문자열로 넘어오는 것이었다. 그런데 쿼리의 enabled 조건이 두 값을 모두 요구해서 쿼리 자체가 실행되지 않았다. 요청이 안 나갔으니 에러도 없다. 화면만 조용히 비어 있었다.

enabled 가드는 “불필요한 요청을 막는” 좋은 장치인데, 값이 없는 상황을 정상 상태로 취급해버려서 실패가 보이지 않게 만들었다. 조회 함수에서 값이 비면 목록을 먼저 조회해 복구하도록 고치고 enabled 조건을 완화했다.

조용히 아무것도 안 하는 것이 가장 나쁜 실패 모드다. 이 프로젝트에서 두 번 같은 형태로 만났다.

결과

항목내용
장애 범위페이지 전체 실패 → 해당 행의 해당 셀만 축소 표기
원인 추적실패한 행을 컨텍스트와 함께 로그로 특정
유지한 것매퍼의 엄격함 (조용한 오표시 방지)
문서화“무음 실패 금지” 에러 정책을 팀 문서로 명문화

프론트엔드만이 아니라 백오피스 전용 백엔드(Spring Boot + JPA)에도 대시보드 API 를 직접 추가했고, Vitest 환경을 세팅해 저장소 테스트 대부분(약 193케이스)을 작성했다. PR 리뷰와 머지를 맡아 브랜치·릴리스 흐름도 운영했다.

되돌아보면

“엄격하게 만들자”까지만 생각했고, “그래서 실패하면 어디까지 무너지나”는 생각하지 않았다. 안전장치를 설계할 때 실패 경로를 함께 설계하지 않으면 안전장치 자체가 장애 원인이 된다.

예외를 던지는 코드에서는 “이게 던지면 무엇이 같이 죽는가” 가 함께 결정돼야 한다. map 안, 렌더 함수 안, 이벤트 핸들러 밖 — 위치에 따라 폭발 반경이 완전히 다르다.