프론트엔드 API 클라이언트 (JWT) 스킬
이 스킬을 사용해야 하는 경우
이 개념 스킬은 JWT 토큰을 적절히 처리하는 강력한 API 클라이언트를 Next.js에서 구현해야 할 때 사용합니다. 이 스킬은 다음과 같은 상황에 적합합니다:
- Next.js 애플리케이션에서 중앙 집중식 API 통신 계층 생성
- 여러 API 엔드포인트에서 JWT 기반 인증 관리
- 토큰 만료 및 갱신 시나리오 처리
- 오류 응답 파싱 및 처리 표준화
- 안전한 API 통신 패턴 구현
이 스킬은 다음 상황에서 사용해서는 안 됩니다:
- JWT 기반 인증이 없는 애플리케이션
- API 통신이 필요 없는 정적 사이트
- 대체 인증 방법(API 키, OAuth 2.0 클라이언트 자격 증명 등)을 사용하는 애플리케이션
- API 상호 작용이 최소인 단순한 애플리케이션
전제 조건
- Next.js 애플리케이션 (App Router 또는 Pages Router)
- JWT(JSON Web Token) 개념에 대한 이해
- HTTP 헤더 및 인증 메커니즘에 대한 지식
- 비동기 JavaScript 작업에 대한 기본적인 이해
- 클라이언트 측과 서버 측 실행 컨텍스트의 차이 인식
개념적 구현 프레임워크
권한 부여 헤더 첨부 기능
- 인증 헤더로 JWT 토큰을 API 요청에 자동 첨부
- 요청 유형 및 엔드포인트에 따라 토큰 포함 시기 결정
- 클라이언트 측 및 서버 측 요청 모두에 대한 토큰 첨부 처리
- 교차 출처 요청에서 적절한 토큰 포함 관리
- 올바른 헤더 형식 보장 ("Bearer ")
토큰 만료 처리 기능
- API 요청 전 JWT 토큰 만료 감지
- 자동 토큰 갱신 메커니즘 구현
- 토큰 갱신 실패를 적절히 처리
- 토큰 갱신 중 세션 연속성 유지
- 여러 동시 요청 간 토큰 갱신 조정
- 갱신 후 업데이트된 토큰을 안전하게 저장
오류 응답 파싱 기능
- API 엔드포인트의 구조화된 오류 응답 파싱
- 특별 처리를 위한 인증 관련 오류(401, 403) 식별
- 사용자 피드백을 위한 의미 있는 오류 메시지 추출
- 다양한 오류 응답 형식을 일관되게 처리
- 클라이언트 오류, 서버 오류 및 네트워크 문제 구분
- 오류 유형에 따라 적절한 사용자 피드백 제공
API 호출 중앙화 기능
- 모든 API 통신을 위한 통합 인터페이스 생성
- 애플리케이션 전반의 요청 및 응답 처리 표준화
- 일관된 오류 처리 및 로깅 구현
- 교차 관심사를 위한 요청/응답 인터셉터 관리
- 타입 안전 API 호출 패턴 제공 (TypeScript 사용 시)
- 적절한 경우 요청 캐싱 및 중복 제거 활성화
예상 입력/출력
입력 요구 사항:
-
JWT 토큰 관리:
- 인증을 위한 유효한 JWT 토큰
- 토큰 갱신 엔드포인트 구성
- 토큰 저장 메커니즘 (localStorage, cookies 등)
- 토큰 만료 시간 및 갱신 타이밍
-
API 구성:
- 요청을 위한 기본 API URL
- 요청 시간 초과 설정
- 사용자 정의 헤더 및 요청 옵션
- 엔드포인트별 구성
-
요청 매개변수:
- HTTP 메서드 (GET, POST, PUT, DELETE 등)
- 요청 URL 또는 엔드포인트 식별자
- POST/PUT 작업을 위한 요청 본문
- 쿼리 매개변수 및 경로 변수
출력 형식:
-
성공적인 API 응답:
- HTTP 200-299 상태 코드
- 예상 형식과 일치하는 파싱된 응답 데이터
- 해당하는 경우 업데이트된 토큰 정보
- 모든 엔드포인트에서 일관된 응답 구조
-
인증 오류 응답:
- 만료/유효하지 않은 토큰에 대한 HTTP 401 Unauthorized
- 자동 토큰 갱신 시도
- 갱신 실패 후 로그인 페이지로 리디렉션
- 인증 문제에 대한 명확한 오류 메시지
-
권한 오류 응답:
- 권한 부족에 대한 HTTP 403 Forbidden
- 권한 수준에 따른 적절한 오류 처리
- 액세스 제한에 대한 사용자 피드백
-
일반 오류 응답:
- 메시지 및 코드가 포함된 구조화된 오류 객체
- 적절한 HTTP 상태 코드
- 디버깅을 위한 상세 오류 정보
- UI 표시를 위한 사용자 친화적인 오류 메시지
통합 패턴
클라이언트 측 통합
- 클라이언트 컴포넌트 및 클라이언트 측 렌더링에서 API 호출 처리
- 브라우저 컨텍스트에서 토큰 저장 및 검색 관리
- 헤더 첨부를 위한 요청 인터셉터 구현
- 인증 상태 관리와 조정
서버 측 통합 (해당하는 경우)
- 서버 컴포넌트에서 API 호출 처리
- 서버와 클라이언트 간 토큰 전송을 안전하게 관리
- 서버 측 토큰 검증 구현
- 서버 측 오류 응답을 적절히 처리
React 컴포넌트 통합
- 함수형 컴포넌트에서 API 통신을 위한 훅 제공
- 컨텍스트 기반 API 클라이언트 액세스 활성화
- 함수형 및 클래스형 컴포넌트 패턴 모두 지원
- 적절한 정리 및 취소 메커니즘 구현
보안 고려 사항
- 토큰 저장: XSS 공격을 방지하기 위한 안전한 JWT 토큰 저장
- 헤더 전송: 모든 API 통신에 HTTPS 사용
- 토큰 갱신: 안전한 토큰 갱신 메커니즘 구현
- 오류 정보: 오류 메시지에 중요한 정보 노출 방지
- 요청 검증: 요청 전송 전 요청 매개변수 검증
- 응답 검증: 응답 무결성 및 형식 확인
- 교차 사이트 요청: 적절한 CORS 처리 구현
성능 영향
- 최소한의 오버헤드를 위한 토큰 검색 및 첨부 최적화
- 요청 차단을 방지하기 위한 효율적인 토큰 갱신 구현
- 성능 향상을 위한 요청 캐싱 전략 고려
- 적절한 상태 관리를 통해 중복 API 호출 최소화
- 적절한 경우 요청 일괄 처리 구현
- 네트워크 요청 타이밍 모니터링 및 최적화
오류 처리 및 검증
- 요청 전 JWT 토큰 형식 및 만료 검증
- 네트워크 연결 문제를 적절히 처리
- 일시적 오류에 대한 재시도 메커니즘 구현
- 중요한 API 오류에 대한 대체 동작 제공
- 중요한 정보 노출 없이 디버깅을 위한 적절한 오류 로깅
- 서비스 복원력을 위한 회로 차단기 패턴 구현
테스트 고려 사항
- 유효/유효하지 않은 토큰으로 토큰 첨부 기능 테스트
- 토큰 갱신 메커니즘이 올바르게 작동하는지 확인
- 다양한 오류 유형에 걸친 오류 응답 파싱 검증
- 클라이언트 및 서버 컨텍스트 모두에서 API 클라이언트 동작 테스트
- 요청의 적절한 정리 및 취소 확인
- 동시 요청 처리 및 토큰 갱신 조정 테스트