[FEATURE] Clerk 토큰 기반 보호 API 요청 구조 공통화

[kbh0218]

Closes #41

개요

Clerk 기반 Google 로그인 및 회원 동기화 흐름은 유지하면서, 이후 백엔드 보호 API를 호출할 때 재사용할 수 있는 공통 API 요청 구조를 정리했습니다.

기존 프론트엔드에는 로그인 성공 후 /api/v1/auth/me를 호출해 Clerk 사용자와 백엔드 member를 동기화하는 흐름이 이미 구현되어 있었습니다. 이번 작업에서는 /auth/me를 새 로그인 API처럼 새로 연동하지 않고, 기존 역할인 Clerk JWT 검증 및 member 확인/동기화 API로 유지했습니다.

대신 이후 analyses, saved-links, 북마크, 삭제 API처럼 인증이 필요한 API를 연동할 때 Clerk getToken()으로 받은 토큰을 Authorization: Bearer {token} 헤더에 일관되게 포함할 수 있도록 공통 API 클라이언트를 추가했습니다.

또한 백엔드 응답이 { data: ... } 형태로 내려오는 구조를 공통으로 처리하고, API base URL 설정과 에러 응답 처리도 한곳에서 관리하도록 정리했습니다. 기존 약관 API처럼 인증이 필요 없는 요청은 비인증 요청 함수로 분리해 공통 구조와 충돌 없이 동작하도록 변경했습니다.

주요 구현 내용

• 공통 API 클라이언트 api/api-client.ts 추가
• Android 에뮬레이터 기본 API 주소를 http://10.0.2.2:8080으로 설정
• 웹/기본 환경 API 주소를 http://localhost:8080으로 설정
• EXPO_PUBLIC_API_BASE_URL 환경변수로 API base URL 재정의 가능하도록 처리
• API base URL의 trailing slash 정규화 처리
• 백엔드 ApiResponse<T> 응답의 { data: ... } 래핑 구조 공통 해제
• 직접 payload가 내려오는 경우도 fallback으로 처리
• 공통 ApiError 타입 추가
• 백엔드 에러 응답의 message, code, errors를 공통 에러 객체로 변환
• JSON 응답이 아니거나 빈 응답인 경우도 공통 요청 함수에서 처리
• 204 No Content 응답 처리 추가
• 인증이 필요 없는 API 요청을 위한 publicApiRequest 추가
• 인증이 필요한 API 요청을 위한 authenticatedApiRequest 추가
• Clerk getToken() 결과를 검증하고 세션 토큰을 가져오는 getClerkSessionToken 추가
• 보호 API 요청 시 Authorization: Bearer {token} 헤더 자동 주입
• 기존 /api/v1/auth/me 회원 동기화 흐름을 공통 API 클라이언트 기반으로 변경
• 기존 약관 API를 공통 비인증 API 요청 구조로 변경

파일별 역할

• api/api-client.ts: API base URL 설정, 공통 요청 함수, 인증/비인증 요청 분리, Clerk 토큰 주입, { data } 응답 래핑 해제, 공통 에러 처리
• services/auth-api.ts: 기존 /api/v1/auth/me 회원 동기화 API 호출 유지, 공통 API 클라이언트 기반으로 요청 방식 변경
• api/terms.ts: 약관 API의 자체 base URL/응답 파싱/에러 처리 로직을 제거하고 publicApiRequest 기반으로 변경

해결한 이슈 목록

• 현재 Clerk 기반 Google 로그인 및 세션 유지 흐름 확인
• 기존 /api/v1/auth/me 호출 위치와 역할 확인
• /auth/me를 새 로그인 API가 아닌 기존 member 확인/동기화 흐름으로 유지
• /auth/me 사전 호출에만 의존하지 않고 보호 API 요청마다 Clerk 토큰을 포함할 수 있는 구조로 정리
• 기존 services/auth-api.ts의 역할과 유지해야 할 동작 확인
• 기존 api/terms.ts의 base URL, 응답 파싱, 에러 처리 방식 확인
• API base URL 설정 공통화
• Clerk getToken()으로 받은 토큰을 보호 API 요청 헤더에 재사용 가능하게 주입
• 인증이 필요한 API와 인증이 필요 없는 API 호출 방식 분리
• 백엔드 { data: ... } 응답 래퍼를 공통으로 처리
• 공통 API 요청에서 성공 응답과 에러 응답을 일관되게 처리
• 약관 API처럼 인증이 필요 없는 API가 공통 구조와 충돌 없이 동작하도록 정리
• 이후 분석 요청, polling, 저장 링크 API 연동에서 재사용 가능한 구조 마련

체크 사항

• 앱 로그인 후 /api/v1/auth/me 200 응답 확인
• 백엔드 로그에서 ApiResponse[data=MeResponse[publicId=...]] 응답 확인
• Docker DB에서 member 동기화 확인
• 비인증 약관 API GET /api/v1/terms/terms_of_service 200 응답 확인
• 약관 API 응답이 { data: ... } 구조로 내려오는 것 확인

참고

이번 작업은 보호 API 요청 구조를 공통화하는 기반 작업입니다.

분석 요청 POST /api/v1/analyses, 분석 polling, 저장 링크 POST /api/v1/saved-links, 북마크/삭제 API 실제 화면 연동은 후속 작업에서 진행합니다.

[minsoo0506]

공통 API 클라이언트 분리, { data } 응답 언랩, 인증/비인증 요청 분리, 기존 auth/me와 terms 호출부 전환 모두 문제 없어 보입니다!

수고하셨습니다 :)