• 어떤 화면은 API 실패 시 Alert만 표시된다.
• 어떤 화면은 데이터가 없는 것처럼 빈 화면만 보인다.
• 인증이 만료되어도 자동 갱신되지 않고 바로 로그인 화면으로 이동한다.
• 렌더링 예외가 발생하면 페이지 전체가 깨진다.

처음에는 각각 독립적인 버그처럼 보였지만, 원인을 추척해 보니 모두 예외 처리 구조가 일관되지 않다는 하나의 문제로 연결되어 있었다.

이번 글에서 단순히 버그를 수정하는 것이 아니라, 프로젝트의 예외 처리 구조를 어떻게 다시 설계했는지 정리해보려고 한다.

1. 문제 상황

1) Interceptor가 존재하지만 실제로 사용되지 않음

가장 먼저 실제 API 호출 흐름을 확인했다. 프로젝트에서는 이미 토큰 자동 갱신과 공통 에러 처리를 위한 axiosInstance가 존재했다.

하지만 실제 호출 경로를 확인해 보니 검색 결과는 자기 자신뿐이었다.

$ grep -rl "axiosInstance" src 
src/api/axiosInstance.js

반면 실제 API 호출은 모두 ApiUtil.js에서 axios.post()를 직접 호출하고 있었다.

즉, axiosInstance.js 파일에 토큰 자동 갱신, 공통 에러 분류, 인터셉터 기반 예외 처리 모두 구현되어 있었지만 실제로는 단 한번도 실행되지 않는 코드였다.

2) 같은 에러도 화면마다 처리 방식이 다름

API 실패시 어떤 화면은 Alert를 띄우거나 데이터를 비운채 종료하거나 아예 catch 조차 하지 않았다. 예를 들어 마이페이지에서는

const response = await meService(); 
setUserInfo(response.data); 
if (!userInfo) return null;

API가 실패하면 userInfo는 끝까지 null인 상태로 남고, 사용자는 아무런 안내 없이 빈 화면만 보게 된다.

또 다른 화면은

if (notifications.length === 0) return null;

정말 알림이 없는 것인지, 조회가 실패한 것인지조차 구분할 수 없었다.

3) 렌더링 예외는 페이지 전체 정애로 이어짐

프로젝트에는 Error Boundary가 존재하지 않았다. 따라서 하나의 Feature에서 렌더링 예외가 발생하면 리액트 특성상 페이지 전체가 깨질 가능성이 있었다.

결국 문제는 개별 버그가 아니라 예외를 처리하는 기준 자체가 없었다는 것이었다.

2. 해결 방안

무작정 try/catch를 추가하는 방식으로는 문제를 해결할 수 없다고 판단했다.

먼저 예외 처리의 책임부터 다시 정의했다.

백엔드는 왜 실패했는지를 정의한다. 즉,errorCode와 message를 통해 비즈니스적인 실패 원인을 전달한다.

반면 프론트엔드는 그 실패를 받아 아래와 같은 상황을 결정해야 한다.

• 사용자에게 어떤 메시지를 보여줄지
• 자동 복구를 시도할지
• 기능을 계속 사용할 수 있도록 할지
• 운영 환경에서 어떻게 추적할지

이 기준을 바탕으로 4가지 관점으로 예외 처리 구조를 설계했다.

• 예외 처리 기준 표준화
• API 예외 처리 흐름 일원화
• 기능 단위 장애 격리
• 운영 환경에서 추적 가능한 구조

3. 적용

1) 에러 처리 기준 표준화

먼저 ErrorUtils.classify()를 만들었다.

백엔드의 errorCode와 message는 그대로 유지하면서 프론트에서는 DOMAIN, SYSTEM, retryable 같은 공통 정보를 추가했다.

모든 API 에러는 최종적으로 다음과 같은 형태만 받으면 되도록 설정했다.

{ category, code, status, message, retryable, backendErrorCode, raw }

2) API 통신 경로 통합

다음으로 실제 호출되지 않던 Interceptor를 서비스에 연결했다.

기존에는 아래와 같은 구조로 설정되었다.

ApiUtils -> axios.post()

이를 아래와 같은 구조로 변경했다.

ApiUtils -> axiosInstance -> Interceptor

이 과정에서 토큰 자동 갱신, 공통 에러 처리, 인증 예외 처리가 실제 호출 경로에서 동작하기 시작했다. 또한 401 처리 책임도 하나로 통합하여 인증 예외가 여러 곳에서 중복 처리되지 않도록 개선했다.

3) 비동기 예외처리 개선

Before	After
기존에는 API 실패와 데이터가 없는 상태가 같은 UI로 표현되는 경우가 많았다.
이를 공통 InlineErrorFallback 컴포넌트로 변경하면서 실패한 경우, 데이터가 없는 경우를 명확히 구분하고, 재시도가 가능한 에러는 즉시 다시 시도할 수 있는 UI도 함께 제공했다.

4) Feature 단위 장애 격리

마지막으로 Error Boundary를 Feature 단위로 적용했다.

Before	After
이전에는 ProfileCard 하나에서 렌더링 오류가 발생해도 페이지 전체가 영향을 받았다. Feature별 Error Boundary를 적용한 이후에는 해당 영역만 Fallback UI로 대체되고, 나머지 기능은 그대로 사용할 수 있도록 변경했다.

예외가 발생해도 서비스 전체가 멈추지 않는 구조를 만든 것이다.

5) 에러 추적 구조 개선

예외 처리를 공통화하면서 에러를 해결하는 것뿐만 아니라, 원인을 빠르게 추적할 수 있는 구조도 함께 설계했다.

기존에는 각 서비스나 컴포넌트에서 console.error를 제각각 호출하고 있어, 어떤 API에서 어떤 유형의 에러가 발생했는지 파악하기 어려웠다.

이를 개선하기 위해 API 예외와 렌더링 예외의 추적 지점을 각각 하나로 통합했다.

• API 예외는 Axios Interceptor에서 에러를 정규화한 뒤, 요청 URL과 함께 category, code, retryable 정보를 기록하도록 구성했다.
• 렌더링 예외는 Feature Error Boundary에서 featureName과 componentStack을 함께 기록하여 어느 기능에서 예외가 발생했는지 확인할 수 있도록 했다.

API Error	Render Error

이후에는 API 오류는 어느 API에서 어떤 유형의 에러가 발생했는지, 렌더링 오류는 어느 기능에서 예외가 발생했는지를 동일한 방식으로 추적할 수 있게 되었다.

또한 추적 로직을 한 곳으로 모아두었기 때문에, 추후 Sentry와 같은 모니터링 서비스를 도입하더라도 해당 지점만 교체하면 동일한 구조를 그대로 활용할 수 있도록 확장성을 고려했다.

4. 검증 과정에서 발견한 또 다른 버그

구현 끝난 뒤 401 토큰 갱신 시나리오를 검증했다.

정상적으로는 아래와 같은 순서로 동작해야한다.

/noti/list (401) -> /users/refresh (200) -> /noti/list 재시도 (200)

하지만 갱신까지 실패하는 시나리오를 테스트하던 중 오히려 새로운 버그를 발견했다.

AUTH_REQUIRED로 전달되어야 하는 인증 예외가 중간에 _SETUP_ERROR로 변경_되고 있었던 것이다.

원인을 추적해 보니 갱신 실패 시 전달되는 refreshError는 이미 동일한 Interceptor를 거쳐 정규화된 에러 객체였다.그런데 이를 다시 ErrorUtils.classify()에 전달하면서 response 정보가 없는 일반 객체로 판단되어 SETUP_ERROR로 재분류되고 있었다.

} catch (refreshError) {
  // 리프레시 토큰 갱신 자체도 실패한 경우 (예: 리프레시 토큰 만료)
  // 리다이렉트 등 사용자 대응은 분류된 에러를 받는 쪽(ApiUtils)이 전담
  console.error("Token refresh failed:", refreshError);
  return Promise.reject(ErrorUtils.classify(refreshError));
}

결국 문제는 이미 분류된 에러를 한 번 더 분류하고 있었다는 것이었다.

} catch (refreshError) {
  // 리프레시 토큰 갱신 자체도 실패한 경우 (예: 리프레시 토큰 만료)
  // refreshError는 /users/refresh 호출이 같은 인터셉터를 거치며 이미 ErrorUtils로 분류된 값이므로 재분류하지 않음
  // 리다이렉트 등 사용자 대응은 분류된 에러를 받는 쪽(ApiUtils)이 전담
  console.error("Token refresh failed:", refreshError);
  return Promise.reject(refreshError);
}

이를 해결하기 위해 갱신 실패 시에는 ErrorUtils.classify(refreshError)를 호출하지 않고, 이미 정규화된 refreshError를 그대로 전달하도록 수정했다.

수정 후 동일한 시나리오를 다시 검증한 결과, 인증 예외가 AUTH_REQUIRED 상태로 일관되게 유지되었고, 이후 로그인 페이지 이동까지 정상적으로 동작하는 것을 확인했다.

4. 결과

이번 개선을 통해 프로젝트의 예외 처리 방식을 화면마다 다르게 구현하는 구조가 아닌, 공통 에러 분류 체계, 일관된 API 예외 처리 흐름, 기능 단위 장애 격리, 재시도 가능한 복구 UI를 갖춘 예외 처리 아키텍처를 구축했다. 또한 401 인증 시나리오를 검증하는 과정에서 이중 분류 버그를 발견·수정하며 예외 처리 흐름의 안정성도 함께 확보했다.

배포 이후 1개월 동안 동일 유형의 장애는 재발하지 않았으며, 무엇보다 이번 경험을 통해 예외 처리는 단순히 try/catch를 추가하는 작업이 아니라, 사용자 경험과 시스템 안정성을 함께 설계하는 일이라는 것을 배울 수 있었다.

프로젝트를 진행하다 보니 코드 자체의 복잡도보다 '코드 리뷰 기준의 불일치' 문제가 자주 언급되었다. 분명 같은 코드인데도, 어떤 리뷰어가 보느냐에 따라 피드백이 매번 달라지곤 했다.

• A 리뷰어는 "비즈니스 로직과 UI가 잘 분리되어 구조가 깔끔하다"고 평가한 반면,
• B 리뷰어는 "아키텍처 레이어가 모호해 유지보수 관점에서 위험하다"고 수정을 요구했다.

결국 문제는 피어 리뷰(Peer Review)의 대상인 코드 자체가 아니라, _리뷰어마다 판단하는 기준과 주관이 다르다는 점_이었다. 기준이 흔들리다보니 리뷰 프로세스 전체의 신뢰도와 일관성이 떨어지고 있었다.

2. 문제의 본질: 문서와 실전의 차이

팀 내부에 팀 컨벤션이나 룰이 없는 건 아니였다. 가이드라인이 명확히 존재하는데도 왜 자꾸 이런 문제가 발생하는걸까? 문제를 찬찬히 분석해보니 크게 3가지 원인이 있었다.

• 글로만 존재하던 규칙: 컨벤션이 Wiki에만 기록되어 있다 보니, 실전 코드를 짤 때는 작업자마다 다르게 해석하거나 깜빡하는 경우도 많았다.
• 경험 기반의 주관적 판단: 정량적인 지표가 없다 보니, 리뷰어 개인의 경험과 선호도에 의존해 피드백을 남기게 되었다.
• 심각도의 불일치: 동일한 문제를 발견하더라도, 누군가는 반드시 고쳐야 할 이슈라고 보고 누군가는 개선 제안으로 가볍게 넘겼다.

결국 판단 기준의 비일관성이 핵심이었다. 리뷰어의 주관에 따라 변하는 상황을 정리해야했다.

3. 해결 방안: AI를 리뷰 규칙의 실행 엔진으로 사용하기

이 문제를 해결하기 위해 단순히 "AI에게 코드를 주고 알아서 리뷰해 달라고 하기" 방식은 적합한 해결책이 아니라고 생각했다. 프롬프트가 모호하면 AI 역시 매번 다른 주관적인 답변을 주기 때문이다. 대신 질문의 방향을 조금 바꿔봤다.

우리 팀의 코드 리뷰 기준을 AI가 파싱하고 실행할 수 있는 명확한 규칙 시스템으로 구조화할 수 없을까?

AI에게 무작정 코드를 짜달라고 하거나 알아서 평가하라고 맡기는 게 아니라, 우리가 정해둔 엄격한 리뷰 규칙을 오차 없이 수행하는 규칙 실행 엔진의 역할을 주는 것이다.

4. 정량화를 위한 점수화 설계

일관성을 유지하려면 리뷰 결과를 정량적인 수치로 변환해야한다. 단순히 감상평이 아닌, 명확한 감점 요인과 등급 체계를 설계했다.

[심각도 정의 및 판단 기준]

리뷰어마다 "이건 꼭 고쳐야 하나?" 고민하거나 주관이 개입하지 않도록, 모든 탐지 조건을 IF (안티패턴) ➔ THEN (심각도) 구조로 격리하고 명확한 대응 가이드를 설정했다.

[점수 및 등급 산정 방식]

$$Score = 100 - (5 \times N_{critical} + 3 \times N_{major} + 1 \times N_{minor})$$

최종 산출된 점수에 따라 직관적인 Grade(등급)를 부여하며, 개발자와 리뷰어는 해당 PR의 전체적인 위험도와 머지 가능 여부를 한눈에 파악할 수 있다.

5. Claude Skill 아키텍처 설계

├── 00_overview.md          # 전체 리뷰 프로세스 파이프라인 및 인터페이스 정의
├── 01_architecture.md      # 레이어드 아키텍처 정의 및 Import 제한 규칙
├── 02_state-management.md  # Zustand 상태 관리 및 Facade 패턴 준수 여부
├── 03_component-design.md  # 가독성, 컴포넌트 책임 분리, 중복 UI 탐지
├── 04_api-layer.md         # API 호출부, DTO 맵핑, 에러 핸들링 컨벤션
├── 05_quality-a11y.md      # 웹 접근성 및 성능 최적화(렌더링 성능) 기준
├── 06_scoring-system.md    # Severity 기반 정량 점수 계산 로직 및 등급 표
└── 07_output-format.md     # 최종 마크다운 리포트 포맷 규칙

• 설계 핵심 원칙 이 시스템의 핵심은 “리뷰 기준을 문장이 아니라 실행 가능한 규칙으로 만든 것”이다.

모든 판단은 다음 구조를 따른다:

IF <조건>
THEN <심각도>
BECAUSE <이유>

• 레이어 기반 관심사 분리: 위 검사 파일 순서대로 단계를 격리하여, 하위 레이어 규칙이 상위 레이어를 오염시키지 않도록 차단했다.

• 추상적 서술 배제: "깔끔하게", "가독성 좋게" 같은 형용사는 제거하고 정량적으로 추적 가능한 규칙만 남겼다.

❌ 지양: "컴포넌트 의존성을 최소화하세요." ✔ 지향: IF base layer(common) imports feature/store/api THEN Critical

6. 실제 적용 화면

코드를 제출했을 때 최종 등급 스코어보드와 함께 IF-THEN-BECAUSE 기반의 피드백이 정량적으로 구조화되어 반환된다.

나는 "클라이언트에서 사용자 입력값을 서버로 전송하면, 서버가 이를 해시값으로 변경해 DB에 저장합니다"라고 설명했다. 그러자 매니저님께서 "그렇게 되면 클라이언트에서 서버로 전송되는 중간에 패킷이 가로채일 경우, 사용자의 평문 비밀번호가 그대로 노출될 수 있겠네요."라는 피드백을 주셨다.

솔직히 처음에는 "SSL(HTTPS)이 적용되어 있으면 암호화되니까 괜찮은 거 아닌가?"라고 생각했다. 실제로 SSL은 중간자 공격(MTM)을 통해 패킷이 탈취되어도, 그 내용을 보호해 주는 것은 맞다.

하지만 매니저님의 피드백을 통해, 내가 간과하고 있던 보안 위협을 알게 되었다.

바로 SSL이 보호해 주지 못하는 영역, '클라이언트 사이드'에서의 평문 노출 문제였다. 만약 악성 브라우저 확장 프로그램이나 XSS(Cross-Site Scripting) 공격이 성공한다면, 데이터가 '전송'되기 직전에 평문 비밀번호가 그대로 탈취될 수 있었다.

그래서 이 문제를 해결하기 위해, 클라이언트 단에서부터 데이터를 직접 암호화하는 RSA 비대칭키 암호화를 도입하기로 결정했다.

비대칭키 암호화(RSA) 도입

RSA(Rivest-Shamir-Adleman)는 비대칭키 암호화 알고리즘으로, 공개 키로 암호화하고 개인 키로 복호화 하는 방식

공개 키는 자유롭게 배포할 수 있기 때문에 키 교환 과정에서의 보안 문제가 없다. 클라이언트는 서버의 공개 키로 데이터를 암호화해 전송하면, 서버만이 이를 복호화할 수 있다.

우선 비대칭키 암호화(RSA)를 통해 패스워드를 암호화하는 경우의 순서는 다음과 같다.

1. 로그인 페이지 로드 시, 클라이언트가 공개키를 요청한다.
2. 서버에서 공개키와 개인키를 생성 후, 클라이언트에게 공개키를 전송한다.
3. 클라이언트에서 사용자가 입력한 패스워드를 공개키로 암호화한 후 서버에게 전송한다.
4. 서버는 암호화된 패스워드를 개인키로 복호화한다.
5. 이후 DB에 저장된 패스워드의 해시값과 비교(인증)한다.

백엔드 구현: RSA 키 쌍 생성

프론트엔드에서 암호화를 수행하기 위해서는 먼저 서버에서 신뢰할 수 있는 키 쌍을 생성해야 한다. 백엔드 구현은 Liferay의 EncryptionUil 로직을 참고하여 구현했다.

서버는 java.security.KeyPairGenerator를 통해 2048비트의 RSA 키 쌍을 생성한다. 여기서 중요한 점은 개인키는 서버 메모리에만 안전하게 보관하고, 공개키만 클라이언트에 노출한다.

// 서버 사이드: RSA 키 쌍 생성 로직 (Liferay 기반)
public static KeyPair generateKeyPair() throws Exception {
    KeyPairGenerator generator = KeyPairGenerator.getInstance("RSA");
    generator.initialize(2048); // 2048비트 보안 수준 설정
    return generator.generateKeyPair();
}

// 공개키를 Base64 문자열로 변환하여 프론트엔드에 전달할 준비
public static String getPublicKeyBase64(PublicKey publicKey) {
    return Base64.getEncoder().encodeToString(publicKey.getEncoded());
}

프론트엔드 구현: 암호화 프로토콜 설계

[공개키 로드 및 포맷팅]

서버에서 보내주는 공개키는 순수 Base64 문자열이다. 하지만 JSEncrypt 라이브러리는 PEM 형식(헤더와 푸터가 포함된 형태)을 기대했기 때문에, 서버에서 받은 키를 프론트엔드 단에서 규격에 맞게 가공해야한다.

// 프론트엔드: 서버에서 받은 Base64 키를 PEM 형식으로 변환하여 설정
const encryptPassword = (plainPassword, publicKeyBase64) => {
  const encryptor = new JSEncrypt();

  // PEM 형식 규격에 맞게 헤더/푸터 추가
  const pemKey = `-----BEGIN PUBLIC KEY-----\n${publicKeyBase64}\n-----END PUBLIC KEY-----`;
  encryptor.setPublicKey(pemKey);

  const encrypted = encryptor.encrypt(plainPassword);
  return encrypted;
};

클라이언트 단에서 사용자 입력값을 난수 형태의 암호문으로 변환하는 데 성공했다.

암호화된 데이터를 서버로 전송하는 순간, 에러가 발생했다.

javax.crypto.BadPaddingException: Decryption error

클라이언트 사이드에서는 암호문이 정상적으로 생성되었지만 서버 로그에는 위와 같은 에러가 나타났다.

원인은 Padding(패딩) 방식의 불일치였다.

RSA 암호화는 보안을 위해 평문에 무작위 데이터를 채워넣는데, 서버와 클라이언트의 기본 설정이 달랐던 것이다.

• 클라이언트(JSEncrypt): 기본적으로 PKCS#1 v1.5 패딩을 사용
• 서버(Java): Cipher.getInstance("RSA")로 설정할 경우, 환경에 따라 기본 패딩 값이 달라져 클라이언트가 보낸 패딩 구조를 해석하지 못함

이 문제를 해결하기 위해 백엔드 담당자분과 소통하여, 양측의 암호화 알고리즘 규격을 RSA/ECB/PKCS1Padding으로 통일하기로 했다.

이후로는 서버에서 성공적으로 복호화된 평문 데이터를 확인할 수 있었다.

최종적으로 유저가 로그인 버튼을 누르면 평문 비밀번호는 즉시 암호문으로 변환되어 전송된다. 추가적으로 암호화 직후 평문이 담긴 변수는 즉시 비우도록 처리했으며, 네트워크 탭에서도 실제 비밀번호를 유추할 수 없는 난수만이 노출되는 것을 확인했다.

프론트엔드 개발을 시작한 지 1년 4개월 정도 되었다. 처음 API를 연동할 때는 가장 많이 사용된다는 이유로 axios를 선택했고, 서버에서 받아온 데이터를 useState, useEffect로 관리했다.

그 당시에는 리액트로 개발 전반적인 흐름을 이해하는 데 목적이 있었기 때문에 어떤 라이브러리가 더 적합할지, 데이터를 어떻게 효율적으로 다뤄야 할지 깊이 고민하지 않았다.

첫 프로젝트가 끝난 뒤, 다음 프로젝트부터는 '어떻게 하면 데이터를 더 잘 관리할 수 있을까?', '어떤 라이브러리를 적용하면 좋을까?' 같은 고민을 자연스럽게 하게 됐고, 실제로 적용해보며 하나씩 배워갔다.

개발 초기 API 연동 방식

• 서버 요청은 컴포넌트마다 useEffect 안에서 직접 처리
• 응답 데이터를 useState로 저장해 상태를 관리했고, 로딩/에러 상태도 매번 따로 구현
• 재요청이 필요한 경우도 별도 함수로 직접 작성해서 처리

당시에는 일단 작동만 하면 된다고 생각했고, 코드의 중복이나 성능에 대한 고민은 많지 않았다. 그래서 프로젝트하는 동안 데이터 흐름이 복잡해지고 유지보수도 어렵다는 문제는 느꼈지만 당장은 기한 내에 완성하는 것에만 집중하였다.

다음 프로젝트부터의 변화

현재 진행 중인 프로젝트에서는 React Query를 이용해 서버 데이터를 비동기적으로 관리하고 있다. 프로젝트를 시작하면서 팀원들과 컨벤션을 맞춰보던 중, React Query를 적용하면 더 효율적으로 데이터 관리할 수 있다라는 의견에 도입하게 되었다.

하지만 막상 쓰기 시작하고 보니, 왜 이 라이브러리를 써야 하는지, 어떤 점이 기존 방식보다 나은지에 대해서는 깊게 공부하지 않았다.

그래서 이번 포스팅에서는 내가 직접 경험했던 두 방식(API 연동과 상태 관리 방식)을 비교하면서,** React Query를 왜 써야 하는지** 정리해보려 한다.

기존 방식의 문제점

1. 중복 요청&캐싱 미지원

useEffect(() => {
  fetchAllDosageData(); // 컴포넌트가 마운트될 때 전체 데이터를 가져옴
}, [fetchAllDosageData]);

useEffect를 사용해서 컴포넌트가 마운트될 때마다 API 요청이 발생하고 있다. 이 방식은 캐시를 사용하지 않기 때문에, 같은 데이터를 사용하는 다른 컴포넌트에도 중복 요청이 발생할 수 있다. 이는 불필요한 네트워크 비용, UI 반응 저하, 서버 부하 증가로 이어질 수 있다.

2. 로딩/에러 상태 처리의 반복과 복잡성

const [dosageData, setDosageData] = useState<DosageData[]>([]);

const fetchAllDosageData = useCallback(async () => {
  try {
    const response = await axios.get(
      'https://www.everycare.site/api/v1/medicines/records/list',
      {
        headers: {
          'Content-Type': 'application/json',
          Accept: 'application/json',
          Authorization: `Bearer ${token}`,
        },
        withCredentials: true,
      },
    );
    ...
    setDosageData(groupedData);
  } catch (error) {
    console.error('Failed to fetch dosage data:', error);
  }
}, [token]);

axios 요청 후 결과를 useState로 수동 저장하고 있고 에러 핸들링도 try/catch로 수동 구현하고 있다. isLoading 상태도 따로 없기 때문에, 로딩 중 여부를 UI에 반영하려면 추가 작업이 필요하다. 또한 재요청(refetch)을 하려면 별도의 함수 호출도 추가 작업이 필요하다.

React Query 소개

위와 같은 문제점을 효율적으로 처리해주는 게 바로 React Query였다.

당시에는 간단히 공부하고 적용했지만, 이번 포스팅에서 이 라이브러리가 왜 필요한지, 어떤 점이 기존 방식보다 나은지 자세히 문서화해보겠다.

React Query는 React Component에서 서버의 상태를에서 서버의 상태를 불러오고, 캐싱하며, 지속적으로 동기화하고 업데이트 하는 작업을 도와주는 라이브러리다. Hook을 사용하여 React Component 내부에서 자연스럽게 서버의 데이터를 사용할 수 있는 방법이다.

React Query에 대한 개념은 이전에 작성한 글이 있어서, 이번 포스팅에서는 생략하고 직접 적용하면서 느낀 점과 기존 방식과의 비교에 초점을 맞춰 정리해보려고 한다.

개념이 궁금하다면 React Query로 데이터 흐름, 이렇게 쉬워도 되나요? 참고해보면 도움이 될 것이다.

React Query를 적용한 코드

이벤트 상세 조회 (GET)

const useEventDetail = () => {
  const { id } = useParams();

  const eventId = Number(id);

  const { data } = useQuery({
    queryKey: ['eventDetail', eventId],
    queryFn: () => eventDetail({ eventId }),
  });

  return { data };
};

호스트 생성 요청 (POST)

export const useHostCreation = () => {
  return useMutation<ApiResponse<null>, Error, HostCreationRequest>({
    mutationFn: async (requestBody: HostCreationRequest) => {
      return await createHost(requestBody);
    },
  });
};

React Query를 써야 하는 이유

1. 데이터를 '상태'가 아닌 '캐시'로 관리한다.

React Query는 캐싱 기반의 백엔드 상태 동기화 라이브러리이다. 동일한 queryKey를 기준으로 요청을 캐싱하기 때문에 여러 컴포넌트에서 동일한 데이터를 사용하더라도 네트워크 요청이 한 번만 발생한다. 이는 성능 최적화에 유리하다.

2. 복잡한 상태 관리 없이도 로딩/에러/데이터 상태 등이 자동으로 관리된다.

isLoading, error, data 등 상태가 자동으로 제공돼서 매번 useState로 상태 선언하고, try/catch로 감쌀 필요가 없다. 이는 코드도 간결해지고 일관성도 유지된다.

3. API 요청에 대한 재사용성과 확장성이 높다.

요청 로직이 queryFn으로 모듈화되면서 여러 컴포넌트에서 중복없이 재사용 가능하다. 나중에 stale-time, suspense, pagination 등 기능 확장도 쉬워진다.

React Query를 통해 단순히 "잘 작동하는 코드"가 아니라 "더 효율적이고 안정적인 코드"를 작성하는 방법을 배울 수 있었다.

처음엔 그저 기능이 좋아 보여서 적용했지만, "왜 이 기술을 써야 하는가"를 스스로 생각하고 선택하는 능력이 중요하다는 것을 느꼈다. 이것은 단순한 구현 능력보다도 기술 선택에 대한 판단력이고, 프론트엔드 개발자로서 꼭 필요한 역량 중 하나라고 생각한다.

이전에는 잘 몰랐지만, 라이브러리 하나를 선택하는 기준과 근거를 갖는 것도 좋은 코드를 작성하는 것만큼 중요한 부분이라는 것을 깨달았다.

[1편] JPEG → WebP 전환 후 성능은 어떻게 달라졌을까?

하지만 단순히 “이미지 최적화를 구현했다”라는 결과만 보고 넘어가기보다는 기술적으로 깊이 있게 공부해보려고 한다.

먼저 WebP 개념을 다시 한번 짚고가보자

WebP(Web Picture format)는 Google이 만든 최신 이미지 포맷이다.

JPEG처럼 손실 압축도 되고, PNG처럼 무손실 압축도 지원하며, 투명도(알파 채널), 애니메이션까지 모두 표현할 수 있는 올인원 포맷이다.

실제로 WebP는 다음과 같은 용량 절감 효과를 보여준다

• 무손실 WebP는 PNG보다 약 26% 더 작고
• 손실 WebP는 JPEG보다 25~34% 더 작으며
• 투명도가 포함된 손실 WebP는 PNG보다 최대 3배 더 작을 수 있다.

이러한 결과는 단순히 포맷을 바꿨기 때문만이 아니라, WebP의 압축 방식 자체가 기존 포맷들과 근본적으로 다르기 때문이다.

이제부터 기술적인 측면을 심층적으로 설명해보겠다.

Q) 왜 WebP로 바꾸면 이미지 용량이 줄어들까?

WebP는 Google의 동영상 기술인 VP8 코덱을 활용하여 이미지를 저장할 때 중복된 정보를 예측하고 차이만 저장하는 방식을 사용한다. 또한 무손실 압축은 이미 저장된 픽셀을 재사용하거나 색상 팔레트를 효율적으로 구성해 중복 데이터를 줄인다.

기존에는 투명한 이미지를 저장할 때 PNG를 사용했지만, WebP는 손실 압축과 투명도(알파 채널)를 동시에 지원해 PNG보다 3배 이상 작게 만들 수 있다. 여기에 JPEG보다 더 효율적인 산술 인코딩을 사용하고, 불필요한 메타데이터(EXIF, 색상 프로필 등)를 제거할 수 있어 전체 용량이 더욱 줄어든다.

즉, WebP는 저장방식, 압축 기술, 메타데이터 처리까지 모든 면에서 더 똑똑하게 이미지 데이터를 다루기 때문에 같은 이미지를 더 작게 만들 수 있다.

Q) 단순히 이미지 용량만 줄었는데, 왜 LCP까지 줄어든 이유는 뭘까?

LCP는 화면에서 가장 큰 콘텐츠 요소(주로 가장 큰 이미지나 텍스트)가 사용자 화면에 완전히 렌더링되는 시점까지의 시간을 측정한다.

이때 LCP에 가장 큰 영향을 주는 요소는 다음 두가지이다.

1. 네트워크 지연: 이미지를 받아오는 데 걸리는 시간
2. 브라우저 렌더링: 이미지 디코딩 및 그리기 과정

이전 포스팅에서 적었던 이미지 최적화 후 실제 수치 변화는 다음과 같았다.

• 이미지 용량: 787kB → 84.4kB (89% 감소)
• 네트워크 요청 시간: 662ms → 112ms (83% 감소)
• LCP: 6110ms → 5070ms (약 17% 감소)
• Performance 점수: 56 → 75 (19점 상승)이미지 용량: 787kB → 84.4kB (89% 감소)
• 네트워크 요청 시간: 662ms → 112ms (83% 감소)
• LCP: 6110ms → 5070ms (약 17% 감소)
• Performance 점수: 56 → 75 (19점 상승)

이미지 최적화를 통해 용량이 89% 감소하면서 네트워크에서 이미지를 받아오는 시간 또한 83% 감소했다.

브라우저는 이미지 리소스를 빠르게 내려받은 덕분에, 디코딩 → 렌더링 단계로 더 빨리 진입할 수 있었고, 결과적으로 LCP는 약 17% 줄어든 5070ms로 개선되었다.

이는 브라우저의 렌더링 타임라인에서 네트워크 지연이 렌더링 병목을 만드는 주요 원인이라는 것을 알 수 있다. 이미지 용량을 줄이면 단순히 “전송 속도”만 개선되는 게 아니라, 렌더링 타이밍도 빨라져 LCP까지 개선되는 것이다.

Q) 네트워크 상태가 안좋으면 최적화 효과는 어떻게 달라질까?

이미지 최적화를 통해 페이지 로딩 속도가 빨라진것을 확인할 수 있었다.

하지만 “네트워크 상태가 느릴 때는 최적화 효과가 어떻게 달라질까?”라는 궁금증이 생겼다.

그래서 Network 탭에 Throttling 기능을 활용해 3G 환경에서 실제로 측정해보았다.

• 이미지 용량: 787kB → 84.4kB (89% 감소)
• 네트워크 요청 시간: 662ms → 794ms (20% 증가)
• LCP: 6110ms → 5480ms (약 10%감소)
• Performance 점수: 56 → 56 (변화 없음)

위 결과를 통해 네트워크 상태에 따라 결과가 다름을 확인할 수 있었다. 이러한 차이는 네트워크 속도가 느려짐에 따라 브라우저의 리소스 처리 타이밍이 지연되기 때문이다.

느린 네트워크에서는 단순한 성능 점수보다는 병목이 어디서 발생했는지를 확인하는 것이 중요하다. 이때 핵심적으로 생각해야할 성능 지표는 크게 두가지이다.

1. TTFB(Time to First Byte) - 서버로부터 첫 바이트가 도착하는 시간이다. 이는 서버 응답 속도, 캐싱 여부, CDN 적용 등에 영향 받는다.
2. TTI(Time to Interactive) - 사용자가 페이지와 실제로 상호작용할 수 있게 되는 시간이다. 이는 JS 실행, 이미지 렌더링 등 리소스 처리 병목의 영향 받는다.

결과적으로 이미지 최적화로 용량은 줄었지만, 느린 네트워크에서는 전송 지연(TTFB 증가)과 렌더링 처리 지연(TTI 증가)이 발생하기 때문에, LCP 개선폭이 줄고 Performance 점수 상승 효과가 상쇄되었다.

Q) WebP를 쓰면 성능이 무조건 좋아질까?

WebP는 JPEG, PNG 대비 더 높은 압축률을 제공하지만, 성능이 무조건 좋아지는 건 아니다.

일부 iOS 구버전 Safari나 오래된 브라우저에선 WebP가 지원되지 않아 fallback 처리가 필요하고, WebP 디코딩이 브라우저에 따라 더 많은 CPU 자원을 소모 할 수도 있어 모바일 저사양 기기에서는 오히려 부하가 될 수 있다. 또한 WebP로 변환할 때 alt 태그 누락, 이미지 크기 비율 오류 등이 있으면 SEO나 접근성 측면에서도 문제가 생길 수 있다.

그러므로 무조건적인 포맷 전환보다는 환경에 따라 유연하게 대응하는 이미지 최적화 설계가 필요하다.

그 중 내 티켓 페이지는 사용자가 이벤트 참여를 위해 구매한 티켓들을 카드 형태로 보여주는 페이지이다. 한 티켓 당 호스트가 주최한 이벤트 배너 이미지를 보여주고 있다.

아래 페이지 접근 시, 티켓 목록 이미지가 늦게 로딩되며 첫 화면이 완전히 보이기까지 지연이 발생한다. 한 유저가 여러 티켓을 구매할 수록 구입한 티켓 정보가 많아지게 되는데, 이때 각 이미지 용량이 크면 이미지 로딩 속도가 느려지는 문제가 발생한다.

이로 인해 사용자 체감 성능 저하로 성능 개선이 필요하다고 생각했다.

성능 측정을 통해 어떤 부분을 최적화해야 하는지 판단할 수 있다.

크롬 브라우저에서 제공하는 웹 개발에 도움되는 다양한 툴이 있다.

1. Network 패널: 현재 웹 페이지에서 발생하는 모든 네트워크 트래픽을 상세하게 볼 수 있다.
2. Performance 패널: 웹 페이지가 로드될 때 실행되는 모든 작업을 볼 수 있다.
3. Lighthouse 패널: 구글에서 만든 툴로, 웹 사이트의 성능을 측정하고 개선 방향을 제시해 주는 자동화 툴

→ 이 중에서 Lighthouse를 통해 성능 측정을 한 뒤 개선해보려고 한다.

Lighthouse란?

Lighthouse는 측정한 웹 페이지에서 다섯 가지 지표에 가중치를 적용해 평균값을 계산한 종합 성능 점수이다.

이러한 지표를 웹 바이탈(Web Vitals)이라고 부른다.

• First Contentful Paint(FCP) 페이지가 로드될 때 브라우저가 DOM 콘텐츠의 첫 번째 부분을 렌더링하는 데 걸리는 시간

• Largest Contentful Paint(LCP) 페이지가 로드될 때 화면 내에 있는 가장 큰 이미지나 텍스트 요소가 렌더링되기까지 걸리는 시간

• Speed Index(SI) 페이지 로드 중에 콘텐츠가 시각적으로 표시되는 속도를 나타내는 지표

• Total Blocking Time(TBT) 페이지가 클릭, 키보드 입력 등의 사용자 입력에 응답하지 않도록 차단된 시간을 종합한 지표

• Cummulative Layout Shift(CLS) 페이지 로드 과정에서 발생하는 예기치 못한 레이아웃 이동을 측정한 지표

Lighthouse를 통한 성능 측정

- Performance: 56점
- 주요 성능 지표
- FCP (First Contentful Paint): 4.9초
- LCP (Largest Contentful Paint): 6.4초
- Speed Index: 7.9초

문제 원인 분석

Lighthouse의 진단 결과를 보면 가장 큰 문제는 “이미지”에 있었다.

브라우저가 가장 먼저 보여주려는 주요 콘텐츠(이미지)가 너무 크고, 너무 늦게, 너무 많은 자원과 함께 로딩되고 있었다는 결과를 볼 수 있다.

이벤트 배너 이미지가 성능에 얼마나 영향을 미치는지 알아보기 위해서는 LCP 수치를 확인하면 알 수 있다. 하나의 이미지를 불러오는데 무려 6110ms 시간이 소요되고 있었다.

하지만 Lighthouse가 절대적인 성능 측정의 지표는 아니기 때문에 좀 더 확실하게 성능 개선을 확인하기 위해 네트워크 탭도 확인해봤다.

네트워크 탭을 확인해보니 이미지 용량이 787kB이고, 해당 이미지를 불러오는데 드는 시간은 662ms로, 다른 요소들에 비해 너무 많은 시간이 소요되는 것을 확인할 수 있었다.

[최적화 전 LCP(6110ms)]

[최적화 전 .jpeg 이미지 용량(787kB)]

그래서 어떤 방법으로 성능을 개선할 수 있을지 고민해보았다.

이미지 최적화와 관련된 내용들을 찾아보던 중 구글에서 만든 WebP라는 이미지 포맷이 최적화에 많이 사용된다는 것을 알았다.

WebP란?

구글에서 만든 웹에 최적화된 이미지 포맷이다.

WebP는 이미지 손상을 최소화하면서 png 또는 jpg와 비교했을 때 평균 40% 감소한 크기로 이미지를 압축할 수 있다. 현재 유저가 이미지를 업로드할때 png, jpg, jpeg 파일만 업로드 하도록 설정했는데 이를 webP로 바꾼다면 이미지를 불러올 때 시간이 훨씬 줄어들 수 있겠다고 생각했다.

유저가 이벤트 배너 이미지를 업로드하는 과정에서 이미지 형식을 webP로 바꿔서 업로드 되도록 하는 convertImageToWebP을 구현했다.

const convertImageToWebP = (file: File): Promise<File> => {
  return new Promise((resolve, reject) => {
    const img = new Image();
    const reader = new FileReader();

    reader.onload = () => {
      if (typeof reader.result === 'string') {
        img.src = reader.result;
      }
    };

    img.onload = () => {
      const canvas = document.createElement('canvas');
      canvas.width = img.width;
      canvas.height = img.height;

      const ctx = canvas.getContext('2d');
      if (!ctx) return reject(new Error('Canvas context error'));

      ctx.drawImage(img, 0, 0);

      canvas.toBlob(blob => {
        if (!blob) return reject(new Error('WebP 변환 실패'));
        const webpFile = new File([blob], file.name.replace(/\.\w+$/, '.webp'), { type: 'image/webp' });
        resolve(webpFile);
      }, 'image/webp');
    };

    img.onerror = reject;
    reader.onerror = reject;

    reader.readAsDataURL(file);
  });
};

1. 유저가 업로드한 이미지 읽기

유저가 올린 이미지를 FileReader를 이용해 브라우저가 이해할 수 있는 형태인 데이터 URL로 변환한다. 이 URL은 Image 객체에 넣어 브라우저에서 표시할 수 있도록 준비하는 과정이다.

2. 이미지를 캔버스에 그리기

이미지가 로드되면 브라우저의 <canvas>요소를 생성하고, 그 안에 이미지를 그대로 그린다. 이 과정은 이미지를 가공하거나 포맷을 바꾸기 위해 그림판처럼 복사해놓는 역할을 한다,

3. 캔버스에 복사된 이미지를 WebP로 변환

캔버스에 그려진 이미지를 toBlob() 메서드를 사용해 WebP 포맷이 변환된다.

사진을 직접 첨부한 후 콘솔에서 업로드할 URL을 확인해보면 .webp 포맷이 변환된 것을 확인 할 수 있다!

업로드할 URL: https://gotogetherbucket.s3.~~~.webp

성능 개선 후, LCP와 네트워크 탭을 확인해보니 확실히 성능 개선된 것을 확인할 수 있었다.

• Performance 56점 → 75점 증가 (19점 증가)
• LCP 6110ms → 5070ms 감소 (17% 감소)
• 이미지 용량 787kB→ 84.4kB 감소 (89% 감소)
• 네트워크 탭의 타임(이미지를 불러오는 시간) 662ms → 112ms 감소 (83% 감소)

다음 포스팅에서는 _WebP 최적화가 실제로 어떻게 성능에 영향을 주는지, 기술적인 지표와 개념을 중심_으로 더 깊이 있게 살펴볼 예정이다.

기존 모달 구현 방식

1. useState를 활용한 모달 상태 관리

const [loginModalOpen, setLoginModalOpen] = useState(false);
const [feedModalOpen, setFeedModalOpen] = useState(false);

2. 조건부 렌더링과 ModalPortal을 통한 모달 렌더링

{feedModalOpen && selectedCard && (
          <ModalPortal>
            <FeedDetailCardModal card={selectedCard} onClose={() => setFeedModalOpen(false)} />
          </ModalPortal>
        )}

기존 모달의 문제점

1. 각 모달의 상태를 별도로 관리해야 해서 모달이 많아질수록 상태 관리가 복잡해질 수 있다. 이는 props-drilling 문제를 일으킬 수 있다.
2. ModalPortal은 직접적인 상태 관리를 요구하지 않아 단일 모달에서는 괜찮지만, 여러 모달을 다루려면 각각의 모달에 대한 상태를 별도로 관리해야 하므로 다중 모달을 구현하기에는 상태 관리가 분산되고 복잡해질 수 있다.

위 방법으로 다중 모달을 구현했을 때, 하나의 모달이 열리면 다른 모달이 닫히거나 상태가 변경되는 등의 의존성이 생겨 관리하기가 어려웠다.

상태 관리 복잡성, 모달 간 의존성, 관리 어려움

이렇게 복잡한 모달 흐름을 효율적으로 관리하기 위해 3가지 핵심 요소를 고려했다.

1. 모달을 스택(Stack) 구조로 관리

여러 개의 모달이 겹쳐지는 상황을 자연스럽게 처리하기 위해 배열(Array)을 활용한 스택 구조로 모달을 관리했다.

const [modalStack, setModalStack] = useState<Modal[]>([]);

  const push = (modal: Modal) => {
    setModalStack(prev => {
      const stack = [...prev, modal];
      console.log('Modal Pushed:', stack);
      return stack;
    });
  };

  const pop = () => {
    setModalStack(prev => {
      const stack = prev.slice(0, -1);
      console.log('Modal Popped:', stack);
      return stack;
    });
  };

  const clear = () => {
    setModalStack([]);
    console.log('Modal Stack Cleared');
  };

modalStack은 현재 활성화된 모달들의 배열이며, 가장 마지막에 추가된 모달이 최상위에 위치한다.

push 함수는 새로운 모달을 배열 끝에 추가하고, pop 함수는 배열의 마지막 요소를 제거하는 방식으로 동작한다. 이를 통해 LIFO(Last In, First Out) 방식으로 모달을 자연스롭게 관리할 수 있다.

2. Context API를 활용한 전역 상태 관리

전역적으로 모달 상태를 공유할 수 있도록 Context API를 이용하여 어디서든 모달을 쉽게 열고 닫을 수 있도록 구현했다.

const ModalContext = createContext<ModalContextType | undefined>(undefined);

const ModalProvider = ({ children }: { children: ReactNode }) => {
  const [modalStack, setModalStack] = useState<Modal[]>([]);
  const isModalOpen = modalStack.length > 0;

  return (
    <ModalContext.Provider value={{ modalStack, isModalOpen, push, pop, clear }}>
      {children}
    </ModalContext.Provider>
  );
};

const useModalStack = () => {
  const context = useContext(ModalContext);
  if (!context) {
    throw new Error('useModalStack must be used within a ModalProvider');
  }
  return context;
};

ModalContext를 생성하여 모달 상태와 조작 함수(push, pop, clear)를 전역적으로 관리할 수 있게 했고, useModalStack 훅을 통해 어디서든 ModalContext를 사용해 모달을 조작할 수 있도록 했다.

ModalProvider가 modalStack의 상태를 유지하며, isModalOpen을 통해 현재 모달이 열려 있는지 여부를 쉽게 확인할 수 있도록 구현하였다.

3. React Portal을 이용한 모달 렌더링

일반적으로 모달은 div 내부에서 렌더링하지만, z-index 문제나 레이아웃이 깨지는 문제를 방지하기 위해 React Portal을 사용해 최상위 DOM에서 렌더링하였다.

function ModalPortal() {
  const { modalStack } = useModalStack();
  const node = document.getElementById('portal') as Element;

  return createPortal(
    <div>
      {modalStack.map((modal, index) => (
        <div key={modal.key} className={`z-[${1000 + index}]`}>
          <modal.Component {...modal.componentProps} />
        </div>
      ))}
    </div>,
    node
  );
}

export default ModalPortal;

createPortal을 사용하여 #portal 요소(최상위 DOM)에 모달을 렌더링하면서 부모 요소의 스타일 영향을 받지 않고 독립적으로 렌더링할 수 있도록 했다.

구현하면서 느낀점은 상태 관리의 중요성이었다.

처음에는 모달을 단순히 각 컴포넌트 내에서만 제어하면 충분할 거라 생각했지만, 여러개 모달의 순서를 관리해야 하는 상황에서는 기존 방식으로는 한계가 있었다. 이를 위해 모달을 전역적으로 관리하는 구조가 필요하다고 생각했고, 어떻게 구조화할 것인지에 초점을 두었다.

또한, 모달이 특정 컴포넌트 내부에 종속되면 UI 깨짐이나 제어의 어려움이 발생할 수 있다는 점도 경험했다. 전역적으로 관리한다고 해서 모든 문제가 해결되는 것이 아니라, 어떤 방식으로 상태를 구성하고 조작할 것인지에 대한 명확한 기준을 설정하는 것이 중요했다. 단순한 UI 요소의 관리도 구조적인 사고와 설계가 필요하다고 생각했다.

특정 컴포넌트 내부에서 사용하는 local state, 전역으로 관리하는 global state, 서버에서 받아온 데이터를 관리하는 server state가 있다. React Query는 이 중 server state를 관리하는 최적화된 라이브러리이다.

이번 글에서는 React Query가 서버 상태를 어떻게 최적화하고 관리하는지에 대해 알아보려고 한다.

React Query란?

fetching, caching, 서버 데이터와의 동기화를 지원해주는 라이브러리

→ React 환경에서 서버의 상태를 불러오고, 캐싱하며, 지속적으로 동기화하고 업데이트하는 작업을 도와주는 라이브러리

React Query, 왜 사용할까?

• 클라이언트 상태와 서버 상태의 분리
  • 클라이언트에서 두 상태를 혼합하여 사용할 경우 상태 관리와 로직 작성이 복잡해지고 유지보수가 어려워질 수 있어서 React Query를 사용해서 서버 상태를 따로 관리할 수 있다.
• 최신 상태 유지
  • 일정 시간마다 상태를 업데이트하거나 특정 동작 이후에 상태를 업데이트 할 수 있다.
• 캐싱, 중복 요청 방지
  • 서버에 API 요청하여 받아온 결과를 캐싱하며 중복 요청을 최소화할 수 있다.
• 비동기 요청에 대한 상태 핸들링
  • 비동기 API 요청에 대한 로딩 상태, 결과 값, 에러 상태와 같은 여러가지 상태를 확인하는 기능을 제공한다.

React Query의 대표 기능

useQuery

useQuery Hook으로 수행되는 Query 요청은 GET 요청과 같이 서버에 저장되어 있는 상태를 불러와 사용한다.

const { data } = useQuery(
  queryKey, // 이 Query 요청에 대한 응답 데이터를 캐시할 때 사용할 Unique Key (required)
  queryFn, // 이 Query 요청을 수행하기 위한 Promise를 Return 하는 함수 (required)
  options, // useQuery에서 사용되는 Option 객체 (optional)
);

• queryKey
  • queryKey는 쿼리를 식별하는 고유한 값으로, 배열 형태로 지정한다.
  • useQuery Hook은 요청마다(API마다) 구분되는 Unique Key(aka. Query Key)가 필요하다. React Query는 이 Unique Key로 서버 상태(aka. API Response)로 로컬에 캐시하고 관리한다.
  • 기본적으로 queryFn에서 사용하는 변수는, 변수가 변경될 때마다 자동으로 다시 가져올 수 있게 쿼리 키에 포함돼야 한다.
    • 변수와 상관없이 항상 하나의 쿼리로 처리하고 싶으면, ESLint exhaustive-deaps 규칙을 비활성화 하면 된다.
• queryFn
  • queryFn은 데이터를 가져오는 비동기 함수
  • 반드시 데이터를 반환하거나 오류를 던져야 한다. 던져진 오류는 반환되는 error 객체로 확인할 수 있다.

import { useQuery } from '@tanstack/react-query'

type ResponseValue = {
  message: string
  time: string
}

export default function DelayedData() {
  const { data, error } = useQuery<ResponseValue>({
    queryKey: ['delay', wait],
    queryFn: async () => {
      const res = await fetch(`https://api.heropy.dev/v0/delay?t=${wait}`)
      const data = await res.json()
      if (!data.time) {
        throw new Error('문제가 발생했습니다!')
      }
      return data
    },
    staleTime: 1000 * 10, // 데이터 유효 기간(fresh -> stale)
    retry: 1 // 요청 재시도 횟수
  })
  return (
    <>
      {data && <div>{JSON.stringify(data)}</div>}
      {error && <div>{error.message}</div>}
    </>
  )
}

useMutation

useMutation Hook으로 수행되는 Mutation 요청은 POST,PUT,DELETE 요청과 같이 서버 데이터에 변경 요청을 처리할 때 사용한다.

서버와의 상호작용으로 상태를 변경하고, 실시간으로 UI를 업데이트하거나 에러를 처리하는데 유용하다.

const { mutate } = useMutation( // mutate: 요청을 트리거 하는 함수
  mutationFn, // 이 Mutation 요청을 수행하기 위한 Promise를 Return 하는 함수 (required)
  options, // useMutation에서 사용되는 Option 객체 (optional)
// onSuccess: 요청 성공 콜백 함수, onError: 요청 실패 콜백 함수, onSettled: 성공 여부 상관없이 콜백 함수
);

import React from "react";
import { useMutation } from "react-query";
import axios from "axios";

const addTodo = async (newTodo) => {
  const response = await axios.post("/api/todos", newTodo);
  return response.data;
};

const TodoApp = () => {
  const { mutate, isLoading, isError, isSuccess } = useMutation(addTodo, {
    onSuccess: (data) => {
      console.log("Todo 추가 성공:", data);
      alert("새로운 Todo가 추가되었습니다!");
    },
    onError: (error) => {
      console.error("Todo 추가 실패:", error);
      alert("오류가 발생했습니다. 다시 시도해주세요.");
    },
  });

  const handleAddTodo = () => {
    const newTodo = { title: "React Query 배우기", completed: false };
    mutate(newTodo);
  };

  return (
    <div>
      <h1>Todo List</h1>
      <button onClick={handleAddTodo} disabled={isLoading}>
        {isLoading ? "추가 중..." : "Todo 추가"}
      </button>
      {isSuccess && <p>Todo가 성공적으로 추가되었습니다!</p>}
      {isError && <p>오류가 발생했습니다. 다시 시도해주세요.</p>}
    </div>
  );
};

export default TodoApp;

React Query로 서버 상태를 관리하기

클라이언트 상태와 서버 상태는 웹 애플리케이션에서 데이터를 관리할 때 핵심적으로 구분해야 할 개념이다. React Query는 서버 상태 관리를 간소화하는 데 중점을 둔 라이브러리이다.

클라이언트 상태 vs 서버 상태

[ React Query의 역할 ]

React Query는 서버 상태를 가져오고, 캐싱하며, 필요할 때 자동으로 데이터를 갱신하는 작업을 처리해준다. 이를 통해 클라이언트는 데이터 요청 및 관리의 복잡성을 줄이고, 핵심 로직에만 집중할 수 있다.

React Query를 활용한 서버 상태 관리 방법

1. Query Key로 데이터 상태를 명확히 정의

   • Query Key는 배열 형태로 구성

   • 첫 번째 값은 데이터의 종류를 정의, 이후에는 동적으로 변경되는 변수들을 추가

     const { data } = useQuery(['users', userId], fetchUserData);

     Query Key를 정의함으로써, React Query는 서버에서 데이터를 가져오거나 캐시된 데이터를 반환할 때 이 키를 기준으로 상태 추적

2. 데이터 캐싱과 staletime의 활용

   • 데이터 캐싱: 데이터를 가져온 후, 기본적으로 React Query는 해당 데이터를 메모리에 저장하고, 동일한 요청에 대해 다시 서버로 요청을 보내지 않아 불필요한 네트워크 요청 방지한다.

   • staleTime: 데이터를 얼마나 “신선한” 상태로 유지할지 설정하는 옵션이다. staleTime을 늘리면 데이터를 오래 동안 fresh 상태로 유지할 수 있어 불필요한 요청을 줄이고, 사용자에게 빠른 응답을 제공할 수 있다.

     const { data } = useQuery(
     ['posts'],
     fetchPosts,
     {
       staleTime: 1000 * 60 * 5 // 5분 동안 데이터를 fresh 상태로 유지
     }
     );

3. 네트워크 재연결, 요청 실패 등의 자동 갱신

   • 자동 재연결: 네트워크 연결이 끊어진 경우, React Query는 자동으로 네트워크가 재연결되면 데이터를 다시 가져온다.

   • 요청 실패 처리: 요청이 실패할 경우, React Query는 자동으로 재시도하거나, 옵션에 따라 수동으로 재시도를 유도할 수 있다.

     const { data, error } = useQuery(
     'posts',
     fetchPosts,
     {
       retry: 3, // 요청 실패 시 최대 3번까지 재시도
       refetchOnWindowFocus: true // 윈도우 포커스를 다시 얻을 때 자동으로 데이터 갱신
     }
     );

마무리

React Query를 알기 전, fetch나 axios로 데이터를 가져오고, 로딩 상태를 관리하며, 실패 시 재시도 로직, 에러 메세지를 표시하는 작업을 전부 직접 구현하며 서버 상태를 관리했다. 이 방식은 코드가 반복적이고, 상태관리가 복잡해지는 문제가 있었다. 또한 모든 상황을 일일이 다뤄야 해서 코드의 가독성이나 유지 보수가 어려웠다.

이런 문제를 해결하기 위해 React Query를 적용해보았고 이전에 모든 경우를 직접 설정해야 했지만, 자동 캐싱과 데이터의 자동 갱신을 통해 데이터를 효율적으로 관리해 주었다. 이후 서버 상태 관리가 훨씬 간소화되고, 코드의 중복도 줄어드는 등 많은 장점이 있었다.

이전처럼 단순히 코드 구현에만 집중하는 것이 아니라, 하나의 API 연동하더라도 서버와 클라이언트 간의 데이터 흐름 등 고려해야하는 부분이 많다는 것을 느꼈다. 앞으로도 더 나은 코드 품질과 성능을 위해 다양한 도구와 패턴을 공부하며 적용할 것이다.

Ref 카카오페이 프론트엔드 개발자들이 React Query를 선택한 이유 TanStack Query(React Query) 핵심 정리

Feature-Sliced Design(FSD) 도입

이전 프로젝트에서는 src 디렉토리 내에 api, components, hook 등 역할별로 폴더구조를 사용했다. 이 폴더 구조로는 많은 단점이 있었다.

// 이전 프로젝트의 폴더 구조  
📦src
┣ 📂api
┣ 📂assets
┣ 📂components
┣ 📂hooks
┣ 📂pages
┣ 📂routes
┣ 📂shared
┗ 📂util

1. 폴더 내 파일 수가 증가할수록 해당 파일을 찾는 데 많은 시간 소요와 관리의 어려움
2. 역할별로 파일이 분리되어 있지만, 모듈 간 의존성이 복잡해지면서 코드의 가독성과 유지보수성 저하

이외에도 여러 문제를 해결하기 위해, 이번 프로젝트에서는 FSD(Feature-Sliced Design)구조를 적용해보려고 한다. 특히 이번 프로젝트는 이전보다 규모가 커졌기 때문에, 기능 단위로 구조를 나누는 FSD가 코드 관리와 유지보수에 더 효율적일거라 생각했다.

🗂️ FSD 아키텍처란?

Feature-Sliced Design(FSD)는 프론트엔드 애플리케이션의 구조를 잡는 아키텍처 방법론이다. 소프트웨어 시스템 기능 중심으로 나누어 모듈화하고, 각 기능을 독립적으로 관리하는 방식이다.

FSD는 전체적으로 layer, slice, segment의 총 3depth로 이루어져있다.

Layers

layer는 최상위 depth로 기존에는 7개였으나 process layer는 현재 사용되지 않기에 6개로 구성하고 있다.

layer 프로젝트의 논리적 단위이며, 각 layer 특정 역할을 담당한다. 이는 다른 layer에 의존하거나 영향을 미칠 수 있다.

• app: 프로젝트의 최상위 계층으로 앱을 실행하는 모든 것을 담당한다. Provider, Router, 전역 스타일 및 타입 등이 여기에 정의대며 app의 entry point 역할한다.
• pages: 개별 페이지의 구현을 담당한다.
• widgets: 재사용 가능한 UI 구성 요소를 포함한다. 쉽게 말해, UI 큰 틀은 같고 안의 내용만 바뀌는 것들이 포함한다.
• shared: 모든 계층에서 사용될 수 있는 유틸리티와 공통 컴포넌트들 포함
  • slice가 존재하지 않고 바로 segments 파일 존재
• features: 특정 기능을 구현하는 데 필요한 모든 것을 포함한다.
• entities: 도메인 모델과 관련된 모든 것

📌 기존의 components 폴더의 역할 분리

기존에 components로 묶여있던 요소들은 features와 entities로 구분한다.

<Shared.Button
    onClick={forkFeature.api.fork}
    icon={shared.icon.fork}
    data={forkEntity.model.forkCount}
/>

• features에서 버튼 동작(onClick 등) 정의
• 버튼이 한 페이지에서 말고 여러 페이지에서 재사용이 된다면 shared
• 데이터이므로 entities/api 로 불러옴

Layers(레이어) 간 의존성 규칙

• app 컴포넌트에서는 모든 레이어를 import할 수 있지만 가급적 pages만 import 하다.
• pages 컴포넌트에서는 하위 4개 레이어(widgets, features, entites, shared)만 import 가능하다
• features 컴포넌트에서는 하위 2개 레이어(entities, shared)만 import 가능하다.

하위계층에서 상위계층을 import 할 수 없다.

📂 공개 API: index 파일의 활용

각 디렉토리 index.js 또는 index.ts 파일을 두어, 외부로 공유할 컴포넌트만 export한다.

📦src
 ┣ 📂pages
 ┃ ┃ ┣ 📜home.tsx
 ┃ ┃ ┣ 📜profile.tsx
 ┃ ┃ ┣ 📜about.tsx
 ┃ ┃ ┗ 📜index.ts

// index.ts
export {about} from'./about';

index 파일에서 export 하지 않으면 해당 파일은 외부에서 사용할 수 없다.

Slice

6개의 layer들은 slice라고 하는 하위 디렉토리가 있다.

slice의 주요 목표는 코드를 값 별로 그룹화 하는 것이다. slice는 layer처럼 특정하게 정해진 이름은 없어 목적에 맞게 구조를 나눈 뒤 이름을 붙이면 된다.

Segment

각 슬라이스 내에서 기능을 더 세분화한 단위이다. 일반적으로는 api, ui, model로 구분된다. segment 또한 목적에 따라 segment에서 나뉘어서 구현된다.

• api: 필요한 서버 요청 담당(fetch, axios등)
• ui: 화면 담당(컴포넌트)
• model: 비즈니스 로직(상태와 상호작용)
• lib: slice 내에서 사용되는 보조기능, util 함수의 성격
• config: 필요한 상수 값들을 담당

FSD 폴더 구조 적용

실제 프로젝트에서 이벤트 등록 페이지를 퍼블리싱을 위해 FSD를 적용한 폴더구조이다.

📦src
 ┣ 📂app
 ┃ ┃ ┣ 📜store.ts // 애플리케이션의 전역 상태 관리
 ┃ ┃ ┗ 📜index.tsx
 ┃ ┃ ┣ 📂 routes
 ┃ ┃ ┃ ┣ 📜Routes.tsx // 라우터 설정과 네비게이션을 담당하는 파일
 ┃ ┃ ┃ ┣ 📜routes.ts // 앱의 라우트 경로들을 정의
 ┣ 📂pages
 ┃ ┃ ┣ 📂 eventCreation
 ┃ ┃ ┃ ┣ 📜FunnelPage.tsx
 ┣ 📂widgets // 재사용 가능한 페이지 수준 UI 컴포넌트 관리
 ┃ ┃ ┣ 📂 eventCreation
 ┃ ┃ ┃ ┣ 📂ui
 ┃ ┃ ┃ ┃ ┣ 📜HostSelectPage.tsx
 ┃ ┃ ┃ ┃ ┣ 📜EventTitlePage.tsx
 ┃ ┃ ┃ ┃ ┣ 📜EventDurationPage.tsx
 ┃ ┃ ┃ ┃ ┣ 📜EventDetailsPage.tsx
 ┃ ┃ ┃ ┃ ┣ 📜EventTypeLocationPage.tsx
 ┃ ┃ ┃ ┃ ┗ 📜EventTagsPage.tsx
 ┃ ┃ ┃ ┃ ┣ 📂config
 ┃ ┃ ┃ ┃ ┃ ┗ 📜funnel.ts
 ┣ 📂features // 특정 기능 단위의 구현을 담당
 ┃ ┃ ┣ 📂 manage-event
 ┃ ┃ ┃ ┣ 📂model
 ┃ ┃ ┃ ┃ ┣ 📜eventCreationStore.ts // 이벤트 생성 상태 관리
 ┃ ┃ ┃ ┃ ┗ 📜eventCreationModel.ts // 비즈니스 로직: 데이터 유효성 검사나 이벤트 생성 등 로직
 ┃ ┃ ┃ ┣ 📂api
 ┃ ┃ ┃ ┃ ┣ 📜createEventAPI.ts
 ┃ ┃ ┃ ┃ ┗ // 나중에 조회, 삭제 api 추가
 ┃ ┃ ┃ ┣ 📂ui
 ┃ ┃ ┃ ┃ ┣ 📜BannerUpload.tsx
 ┃ ┃ ┃ ┃ ┣ 📜LocationSearchInput.tsx
 ┃ ┃ ┃ ┃ ┣ 📜MapView.tsx
 ┃ ┃ ┃ ┃ ┣ 📜LocationList.tsx
 ┃ ┃ ┃ ┃ ┣ 📜LinkInputBox.tsx
 ┃ ┃ ┃ ┃ ┣ 📜EventTypeBox.tsx
 ┃ ┃ ┃ ┃ ┣ 📜EventDetail.tsx
 ┃ ┃ ┃ ┃ ┣ 📜CategoryDropdown.tsx
 ┃ ┃ ┃ ┃ ┗ 📜HashTagDropdown.tsx
 ┃ ┃ ┃ ┃ ┗ 📜FunnelUi.tsx
 ┣ 📂entities // 도메인 데이터 모델 및 관련 로직
 ┃ ┃ ┣ 📂config
 ┃ ┃ ┃ ┗ 📜event.ts
 ┣ 📂shared // 모든 계층에서 사용되는 공통 모듈, 유틸리티, 스타일
 ┃ ┃ ┣ 📂 ui
 ┃ ┃ ┃ ┣ 📜TextInput.tsx
 ┃ ┃ ┃ ┣ 📜Button.tsx
 ┃ ┃ ┃ ┗ 📜DatePicker.tsx
 ┃ ┃ ┣ 📂 lib
 ┃ ┃ ┃ ┗ 📜dateUtils.ts // 날짜를 처리하는 로직(날짜 계산, 날짜 포맷 변환 등)

이번 프로젝트에서 FSD 폴더 구조를 설계하면서, widgets과 shared, features과 entities 폴더의 역할을 명확히 구분하는 것이 중요했다. 각 폴더의 목적과 구성 요소를 비교하면서, 어떻게 재사용성과 의존성을 고려했는지 작성해보겠다.

1. widgets 폴더와 shared 폴더 비교

widgets shared 폴더는 모두 재사용 가능한 UI 컴포넌트를 다루지만, 사용 범위와 목적에서 차이가 있다.

• widgets: 페이지 수준의 UI 컴포넌트들을 포함한다. 즉, 특정 페이지에서만 사용되는 UI 구성 요소들을 모아둔 곳이다.
  • 이벤트 생성 페이지에서 사용되는 다양한 UI 컴포넌트들(예: HostSelectPage.tsx, EventTitlePage.tsx)를 widgets 파일에 넣었다. 이 파일들은 특화된 스타일과 로직을 갖고 있어서, 다른 페이지에서 재사용되지 않는다.
• shared: 애플리케이션 전반에서 사용되는 컴포넌트들을 모아둔 곳이다.
  • TextInput.tsx, Button.tsx, DatePicker.tsx와 같은 컴포넌트들은 여러 페이지와 기능에서 재사용될 수 있기 때문에, 가장 하위 폴더인 shared/ui 폴더에 넣었다.

2. features폴더와 entities폴더 비교

features와 entities 폴더는 각각 비즈니스 로직과 도메인 모델을 관리한다.

• features: 특정 기능 단위로 컴포넌트와 로직을 분리한 폴더이다.
  • manage-event 폴더는 이벤트 생성뿐만 아니라 이벤트 조회, 삭제 등 관련 기능을 한 곳에서 관리할 수 있도록 포괄적인 의미를 갖고 있다. 이렇게 하면 이벤트와 관련된 여러 기능을 하나의 기능 단위로 묶어 관리하기에 좋다.
• entities: 도메인 데이터 모델 및 관련 로직을 담고 있다.
  • event.ts는 도메인 데이터를 정의하고, 이 데이터를 처리하는 로직을 포함하고 있다. 기능 단위의 구현보다는 데이터를 중심으로 구성된다.

마무리

이번 프로젝트를 진행하다보니 대규모 프로젝트가 됐다… 기존의 폴더 구조로 진행했다면, 하나의 기능과 관련된 코드 파일을 찾는 데 많은 시간이 걸렸을 것이다. 하지만 기능별로 분류하는 FSD(Feature-Sliced Design)를 적용하면서, 파일을 효율적으로 관리하고 각 기능의 역할을 명확히 구분 할 수 있었다.

프로젝트의 특징에 맞는 폴더 구조를 적용하는 것의 중요함을 알게 되었다. 폴더 구조에 정해진 정답은 없지만, 프로젝트의 요구사항과 팀의 작업 방식에 따라 적절한 구조를 선택하는것이 중요하다.

앞으로 프로젝트를 진행할 때, 기존의 폴더 구조만 고수하는 것이 아닌 다양한 파일 구조를 시도해봐야겠다는 생각이 들었다.

Ref FSD 공식문서 아직도 React 폴더 구조로 고민하고 계신가요? FSD 한 번 써보세요[제로초뉴스]