Conv.docs

API 페칭 아키텍처 규칙

기본 구조

  • /src/services: 도메인별 API 모듈
  • /src/hooks: 데이터 페칭 커스텀 훅
  • /src/types: 공통 타입 정의

참고: 전체 디렉토리 구조는 디렉토리 구조 규칙을 참조하세요.

서버 응답 스키마

서버는 일반적인 axios 응답 스키마를 따릅니다:

{
  "data": {},
  "status": 200,
  "statusText": 'OK',
  "headers": {},
  "config": {},
  "request": {}
}

타입 정의 방식

1. 기본 응답 타입 정의 (선택)

서버에서 response.data 내부에 BaseResponse 스키마를 지정한 경우, 다음과 같이 정의합니다. 이후 최종 스키마 타입 정의 시 BaseResponse를 Extends 하여 사용합니다.

// /src/types/baseResponse.ts
export interface BaseResponse {
  // 서버에서 지정한 형식 (예시)
  timestamp: string;
  code: string;
  message: string;
}

2. 엔티티 타입 정의

서버에서 nested json을 제공한 경우, 엔티티 당 타입을 정의합니다. 최대한 모든 속성을 포함하는 인터페이스를 기본 엔티티로 정의하고, Partial/Pick/Omit으로 상황에 맞게 재정의하여 사용합니다.

// /src/server/{domain}/types/{entity}.types.ts
export interface Member {
  memberId: number;
  university: string;
  nickName: string;
  attendance: string;
}

참고: 타입스크립트 활용에 관한 자세한 내용은 TypeScript 활용 규칙을 참조하세요.

3. 도메인별 응답 타입 정의

// /src/server/{domain}/types/{domain}.types.ts
export interface WorkbookResponse {
  nickName: string;
  week: number;
  workbookContents: string[];
  members: Member[];
  checklists: Checklist[];
}

4. API 응답 최종 타입 정의

// /src/server/{domain}/response.ts
export interface GetWorkbookResponse extends BaseResponse {
  result: WorkbookResponse;
}

API 통신 함수

// /src/server/{domain}/{function}.ts
export const getWorkbook = async (
  studyId: number,
  memberId?: number,
  week?: number,
): Promise<GetWorkbookResponse> => {
  const response = await GetAxiosInstance<GetWorkbookResponse>(`/studies/${studyId}/workbooks`, {
    params: {
      memberId,
      week,
    },
  });

  return response.data;
};

참고: API 함수 네이밍 방식은 네이밍 컨벤션 규칙을 참조하세요.

모든 API 함수는 index.ts에서 export하여 모듈 외부에서 쉽게 가져다 쓸 수 있게 합니다:

// /src/server/{domain}/index.ts
export * from './study';
export * from './workbook';
export * from './checklist';

useQuery 커스텀 훅

1. useQuery Props 타입 정의

useQuery의 모든 옵션을 View에서 자유롭게 가져다 쓰기 위해 Props 타입을 정의합니다.

// /src/types/tanstack.ts
export interface UseQueryProps<TData, TError> {
  queryKey?: unknown[];
  options?: Omit<UseQueryOptions<TData, TError>, 'queryKey' | 'queryFn'>;
}

2. 도메인별 useQuery Props 타입 정의

UseQueryProps를 확장해 각 hook의 Props 타입을 정의합니다.

// /src/hooks/{domain}/{domain}.types.ts
export type UseGetWorkbookProps = UseQueryProps<GetWorkbookResponse, Error> & {
  studyId: number;
  memberId?: number;
  week?: number;
};

3. useQuery 커스텀 훅 구현

커스텀 훅을 구현합니다.

// /src/hooks/{domain}/{domain}.ts
export const useGetWorkbook = ({
  studyId,
  memberId,
  week,
  queryKey,
  options,
}: UseGetWorkbookProps) => {
  return useQuery<GetWorkbookResponse, Error>({
    queryKey: [`/studies/${studyId}/workbooks`, memberId, week, ...(queryKey || [])],
    queryFn: () => getWorkbook(studyId, memberId, week),
    ...options,
  });
};

참고: 커스텀 훅의 코딩 스타일은 코딩 컨벤션 규칙을 참조하세요.

코드 분리 원칙

  • 도메인별 디렉토리 분리
  • 엔티티 타입은 별도 파일로 분리하여 재사용성 확보
  • 모든 API 통신 함수와 관련 타입은 index.ts로 export
  • UI 컴포넌트에서 직접 API 호출 금지, 반드시 커스텀 훅 사용
  • 비즈니스 로직과 UI 로직 철저히 분리

사용 예시

const { data, isPending, isSuccess, isError } = useGetWorkbook({
  studyId: studyId,
  week: week,
  memberId: memberId,
});

// isLoading, isPending, isError 등 React Query의 모든 기능 사용 가능

관련 규칙

API 페칭 구현 시 다음 규칙들을 함께 참조하세요:

  • 디렉토리 구조: 디렉토리 구조 규칙 - 전체 프로젝트 구조 및 레이어 아키텍처
  • 네이밍 패턴: 네이밍 컨벤션 규칙 - API 함수 및 타입 네이밍 규칙
  • 코딩 스타일: 코딩 컨벤션 규칙 - 일관된 API 구현 방식
  • 성능 최적화: 성능 최적화 규칙 - 데이터 페칭 성능 최적화