Route Handlers: 챔피언 로테이션 데이터 가져오기

문제 상황

League of Legends 챔피언 로테이션 페이지를 개발하던 중 다음과 같은 두 가지 주요 이슈가 발생

 

1. 잘못된 함수 호출

• fetchChampionRotation 대신 fetchChampionIdsForRotation을 호출하여 콘솔에 빈 배열([])이 출력됨
• IDE 자동 완성 기능이 잘못된 함수를 제안하여 의도치 않게 잘못된 함수를 import함

2. 404 에러

• env.local에 만든 환경변수를 클라이언트에서 사용하기 위한 NEXT_PUBLIC_ 접두사가 누락되어 API 호출 URL이 undefined/api/rotation 으로 처리됨
• 외부 DDragon API 주소(https://ddragon.leagueoflegends.com/api/rotation)로 호출하고 있었으나, 실제로는 로컬 Route Handler(/api/rotation)를 호출해야 했음

 

해결 과정

 

문제 1: 잘못된 함수 호출

rotation 페이지에서 데이터를 가져오기 위해 fetchChampionIdsForRotation을 호출했지만, 이 함수는 필요한 데이터를 올바르게 반환하지 않았다. 원인을 찾아보니  IDE 자동 완성 기능이 utils/index.ts에서 비슷한 이름의 다른 함수를 제안했고 잘못된 함수를 선택함

 

개선 방법

utils/index.ts에서 모든 API 유틸을 한번에 export하지 않고 각 기능별로 파일을 분리 

• utils/clientApi.ts: 클라이언트 측에서 사용
• utils/commonApi.ts: 공통으로 사용
• utils/serverApi.ts: 서버 측 사용

문제 2: 404 오류

함수를 수정한 후에도 404 오류가 지속됐고, 원인 분석 결과 두 가지 문제점을 발견

1. 환경 변수 접근 문제: Next.js에서 클라이언트 컴포넌트에서 환경 변수를 사용하려면 NEXT_PUBLIC_ 접두사가 필요하며 이 접두사가 없으면 클라이언트 측에서 환경 변수 값이 undefined로 처리됨
2. API 경로 오류: 로컬 서버에서 구현한 Route Handler(app/api/rotation/route.ts)를 호출해야 했는데, 잘못된 외부 API 주소(https://ddragon.leagueoflegends.com/api/rotation)를 사용하고 있었음

최종 해결책

환경 변수에 NEXT_PUBLIC 접두사를 추가하고, API 호출 주소를 올바르게 수정하여 문제를 해결했다:

export const fetchChampionRotaion = async () => {
  const LOCAL_SERVER = process.env.NEXT_PUBLIC_LOCAL_SERVER;
  const API_BASE_URL = process.env.NEXT_PUBLIC_API_BASE_URL || LOCAL_SERVER;
  const response = await fetch(`${API_BASE_URL}/api/rotation`, {
    cache: 'no-store',
  });

  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(errorData?.error || 'Failed to fetch champion rotation');
  }

  const data = await response.json();

  return data;
};

 

교훈 💡

1. 클라이언트 환경변수 규칙: Next.js에서 클라이언트 컴포넌트에서 환경 변수를 사용할 때는 반드시 NEXT_PUBLIC 접두사가 필요하다. 이는 보안상의 이유로 설계된 중요한 제약사항이라고 한다.
2. Route Handler 경로 이해: Next.js의 App Router에서 Route Handler의 경로는 파일 시스템 기반 라우팅을 따른다. app/api/rotation/route.ts에 정의된 핸들러는 /api/rotation 경로로 접근해야 한다.
3. URL 변수화 주의점: 다양한 환경(개발, 배포 등)에서 서로 다른 URL을 사용할 때는 변수 구성과 우선순위를 명확히 설정해야 한다.

이런 문제들은 개발 과정에서 흔히 발생하는 실수지만, 체계적인 디버깅 과정을 통해 근본 원인을 파악하고 해결함으로써 Next.js의 동작 원리를 더 깊이 이해하는 기회가 됐다.