🚀 kepler-http – REST API를 구조화하다

개발 초반에는 주로 목업 데이터로 UI만 빠르게 구성해왔지만,

이제는 실제 서버와 통신해서 유저 데이터를 받아오고, 상태에 따라 화면이 바뀌도록 만들어야 한다.

우리는 Swagger로 정의된 REST API를 기준으로 개발을 시작했고,
처음엔 당연히 axios.get(), axios.post()로 데이터를 가져오면 되지 않을까 생각했다.
하지만 API가 늘어나고 화면이 많아지면서,
“이걸 일일이 다 짜는 건 너무 귀찮고, 유지보수도 어렵다”는 결론에 도달했다.

그래서 우리는 직접 만든 API 통신 구조인 kepler-http 를 도입했다.

📦 kepler-http란?

간단히 말하면, kepler-http는
하나의 요청 단위를 명확하게 정의하고,
fetcher 함수 하나로 모든 요청을 처리하도록 만든 통신 미들웨어다.

우리는 요청 단위를 "Wing(윙)"이라고 부르고,
fetcher 함수는 "ShootingStar(슈팅스타)"라고 부른다.
이름은 꽤 유쾌하지만, 기능은 아주 구조적이다.

⚙️ kepler-http 핵심 구성 요소

kepler-http는 다음 세 가지 클래스를 중심으로 구성된다:

• Config – 공통 axios 설정 (baseURL, timeout, 인증 등)

• Auth – 토큰 저장 및 리프레시 설정

• Wing – 요청 단위 (axios config 객체 역할)

이 세 가지를 기반으로 요청 흐름이 동작하며,
이후에 나오는 ShootingStar는 이 구조 위에서 실제 요청을 날리는 fetcher다.

📌 Config – 프로젝트 전체 axios 인스턴스 설정

export class Config {
  baseUrl: string;
  timeout: number;
  headers: KeplerHeaders;
  auth: Auth;
}

Config는 axios 인스턴스를 만들 때 사용하는 공통 설정 객체다.

• baseUrl: 모든 API 요청의 기본 URL

• timeout: 요청 제한 시간

• headers: 공통 헤더 (Authorization 등)

• auth: 인증 처리 로직을 담은 Auth 인스턴스

이건 보통 앱 실행 초기에 한 번 생성되고,
ShootingStar의 생성자에 전달된다:

const config = new Config('https://api.example.com', 10000, auth);
const shootingStar = new ShootingStar(config);

🔐 Auth – 토큰 저장 및 refresh 흐름 설정

export class Auth {
  refreshUrl: string;
}

• 로그인 시 받은 accessToken, refreshToken을 localStorage에 저장

• 로그아웃 시 localStorage 초기화

• 토큰 만료 시 사용할 refresh URL을 관리

const auth = new Auth('/v1/auth/refresh', accessToken, refreshToken);

ShootingStar는 요청 중 401 에러가 나면,
이 Auth.refreshUrl을 이용해 자동으로 토큰을 갱신한다.

📨 Wing – 하나의 요청 단위 (axios config 객체 역할)

export class Wing {
  url: string;
  method: Method;
  needAuth: boolean;
  headers: KeplerHeaders;
  params: KeplerParam;
  data: KeplerBody;
}

Wing은 하나의 요청에 필요한 정보를 모두 담고 있는 클래스다.
말 그대로 axios의 config 객체를 클래스로 감싼 것이다.

const wing = new Wing(
  '/v1/users/123/example',
  Method.GET,
  false,
  exampleParam, // param
  {}           // body
);

ShootingStar.launch()는 이 wing을 받아서 axios 요청을 수행한다.

📋 정리표

클래스	역할											사용 위치
Config	axios 인스턴스 초기화용 설정						new ShootingStar(config)
Auth	토큰 저장 및 refresh 로직						config.auth, refresh 시 사용
Wing	실제 요청 단위 (url, method, param, body 포함)	shootingStar.launch(wing)

🌠 핵심 로직: ShootingStar 코드 리뷰

우선 전체 구조 중 가장 핵심인 ShootingStar 클래스를 하나씩 뜯어보자.
이 fetcher는 결국 axios 래퍼지만, 다음과 같은 역할을 더 가지고 있다:

• 요청 전처리

• 토큰 필요 여부 확인 및 헤더 설정

• 응답 실패 시 토큰 재발급

• 다시 재요청

🔍 1. launch() 메서드: 요청을 날리는 진짜 fetcher

async launch<KeplerData>(wing: Wing): Promise<KeplerResponse<KeplerData>> {

이 함수는 모든 요청을 다 이 함수 하나로 처리한다.
wing 객체에 url, method, param, body, header 등이 다 들어 있고,
필요하면 자동으로 accessToken도 붙는다.

주요 흐름 정리:

if (wing.needAuth) {
  if (localStorage.getItem('accessToken') == '') throw new Error("UnAuthorizedRequest");
  wing.headers = {
    common: {
      Authorization: `Bearer ${localStorage.getItem('accessToken')}`
    },
    post: {}
  };
}

인증이 필요한 요청이면 localStorage에서 accessToken을 꺼내고,

그걸 Authorization 헤더에 붙인다.

그리고 axios 요청:

return await this._instance.request(wing);

🔁 2. 토큰 만료 대응: 실패하면 refresh 후 재요청

if (e.response.status === axios.HttpStatusCode.Unauthorized) {
  let access_token = await this._refreshToken();
  wing.headers.common.Authorization = `Bearer ${access_token}`;
  return await this._instance.request(wing);
}

처음 요청에 실패했더라도,
401 Unauthorized라면 refreshToken을 사용해서 accessToken을 새로 받고,
다시 동일 요청을 재시도한다.

🔁 3. _refreshToken(): accessToken 갱신

private async _refreshToken(): Promise<string> {
  let wing = new Wing(this._config.auth.refreshUrl, Method.POST, true, {}, {
    refresh_token: localStorage.getItem('refreshToken')
  });
  ...
  localStorage.setItem('accessToken', res.data.access_token);
  return res.data.access_token;
}

refresh token을 사용해서 새 토큰을 받아오고,
localStorage에 저장 후 반환.

덕분에 우리는 토큰 만료를 신경 쓸 필요 없이 launch()만 호출하면 된다.

🧱 함께 쓰이는 타입 구조들

kepler-http는 API 요청을 구성할 때
모든 요소(body, param, headers, response)를 명확한 타입으로 분리해서 정의한다.

이건 단순히 타입 안정성을 위한 것만이 아니라,
요청을 모듈화하고 일관된 방식으로 처리하기 위한 설계다.

📌 KeplerHeaders.ts

export default interface KeplerHeaders {
  common: { Authorization: string };
  post: {};
}

요청 헤더를 공통(common)과 POST 전용(post)으로 분리해서 확장성 확보

대부분의 요청에서는 common.Authorization만 사용하지만, 필요한 경우 메서드별 헤더 커스터마이징 가능

📌 KeplerResponse.ts

export default interface KeplerResponse<T extends KeplerData> {
  status: number;
  data: T;
}

모든 응답은 status와 data로 구성

data는 우리가 지정한 타입 (ProfileData, PostData 등)을 제네릭으로 전달

📌 KeplerData.ts

export default interface KeplerData {
  [key: string]: any;
}

모든 응답 타입의 베이스 인터페이스

실제로 사용할 때는 확장해서 구체적인 응답 구조를 정의

예시: schemas/profile/Data.ts

export interface ProfileData extends KeplerData {
  id: string;
  nickname: string;
  profileImage: string;
  level: number;
}

📌 KeplerParam.ts

export default interface KeplerParam {
  [key: string]: string | number;
}

URL 쿼리 파라미터용 타입

요청마다 필요한 파라미터는 따로 정의해서 넘긴다

예시: schemas/profile/Param.ts

export interface GetProfilesParam extends KeplerParam {
  world_id: string;
  game_id: string;
}

📌 KeplerBody.ts

export default interface KeplerBody {
  [key: string]: any;
}

요청 body 타입의 베이스

POST, PATCH 등에서 사용하는 payload 정의

예시: schemas/profile/Body.ts

export interface EditProfileBody extends KeplerBody {
  nickname: string;
  profileImage: string;
}

✅ 요약
파일 설명 예시

KeplerHeaders.ts	헤더 구조 정의	Authorization 등
KeplerResponse.ts	모든 응답의 공통 형태	status, data
KeplerData.ts		응답 타입의 base	ProfileData, PostData
KeplerParam.ts		URL 파라미터 정의	world_id, game_id
KeplerBody.ts		요청 바디 정의	nickname, profileImage

이런 타입 구조를 기반으로
각 요청에 필요한 데이터 조각을 조립한 뒤
Wing 객체로 요청을 생성하고,
ShootingStar.launch()로 전송하는 구조다.