API 관련 폴더 구조 논의

[bbearcookie]

📂 core
    📂 api
        📂 functions: API 요청하는 함수들
            📄 commentAPI.ts
            📄 postAPI.ts
        📂 mutationHooks: 공통화가 필요한 커스텀 useMutation 훅
            📄 useModifyPost.ts
        📂 queryHooks: 공통화가 필요한 커스텀 useQuery & useQueries 훅
            📄 useOddPostQuery.ts
        📂 queries: 기본적으로 매핑할 queryKey, queryFn 정보
            📄 index.ts
            📄 comments.ts
            📄 posts.ts
        📄 instance.ts: axios 인스턴스 객체

개요

최근에 논의했던 query-key-factory의 아이디어를 바탕으로 API에 관한 소스 코드를 어떻게 구조화할지 정리해봤어요! (#2 #4)

1. 먼저 쿼리의 queryKey, queryFn을 매핑해주는 레이어가 필요하기에, queryKeys 라는 디렉토리에 해당 내용을 정리했어요.
2. 세진님이 말씀해주셨던 내용에서처럼 쿼리에 공통적으로 들어가야 하는 옵션이 있을 수 있겠다는 생각을 했어요.
   • 생각해보니 공통 옵션 뿐만 아니라, 공통 로직이 들어가는 경우가 존재할 수도 있겠네요!
   • 그러면 그 부분만 따로 커스텀 훅으로 만드는 방법은 어떨까요? (queries 디렉토리)
   • 거의 대부분의 쿼리 매핑은 queryKeys 디렉토리에서 처리가 될 것이기 때문에 커스텀 훅을 만드는 경우가 잦은 현상은 아닐 것 같지만, 그래도 정말 공통화가 필요한 부분에만 유연하게 대응할 수 있을 것 같아요!
3. mutation은 query에 비해서 명령형으로 처리되기 때문에, 각 mutation간의 공통 로직이 존재하기 쉬울 것 같아요!
   • 예를 들어서, 낙관적 업데이트라던가, 어떤 데이터에 변화가 발생하면 invalidateQuery 처리를 해야 한다던가 하는 로직이 있겠어요!
   • 마찬가지로 그렇다면, mutation도 해당 부분만 적절하게 커스텀 훅으로 묶어내는 건 어떨까요?

요약하자면, 기본적으로 functions 나 queryKeys 에 정의된 내용을 컴포넌트가 직접 불러오는 방법을 사용하되, 정말 공통화가 필요한 부분이 있다면 그 부분에 대해서만 적절하게 커스텀 훅으로 묶어내자는 아이디어입니다!

예시

예시 레포지토리 로 작성해봤는데요!
몇 가지 레이어로 고민했던 내용을 적어볼게요!

1. axios 인스턴스

baseURL 정보를 담아서 사용하는 인스턴스를 생성하고, HTTP 헤더에 공통적인 옵션을 사용해야 하는 경우에는 인터셉터를 정의할 수 있어요!
/api/instance.ts

import axios from 'axios';

const baseURL = 'https://jsonplaceholder.typicode.com';

export const baseInstance = axios.create({ baseURL });
export const authInstance = axios.create({ baseURL });
export const formDataInstance = axios.create({ baseURL });

authInstance.interceptors.request.use(
  (config) => {
    config.headers['Authorization'] = `Bearer ${'사용자 권한을 표현하는 액세스 토큰을 담아요'}`;

    return config;
  },
  (error) => {
    return Promise.reject(error);
  }
);

formDataInstance.interceptors.request.use(
  (config) => {
    config.headers['Authorization'] = `Bearer ${'사용자 권한을 표현하는 액세스 토큰을 담아요'}`;
    config.headers['Content-Type'] = 'multipart/form-data';

    return config;
  },
  (error) => {
    return Promise.reject(error);
  }
);

2. API 요청 함수

생성했던 인스턴스를 바탕으로 실제로 API 요청을 처리하는 함수를 만들어요!
예시로 /api/functions/postAPI.ts 입니다.

import { Post } from '@/types/index';
import { baseInstance } from '../instance';

const postAPI = {
  fetchPosts: async () => {
    const { data } = await baseInstance.get<Post[]>(`/posts`);
    return data;
  },
  fetchPostDetail: async (postId: string) => {
    const { data } = await baseInstance.get<Post>(`/posts/${postId}`);
    return data;
  },
  addPost: async (post: Post) => {
    const { data } = await baseInstance.post<{ message: string }>('/posts', { data: post });
    return data;
  },
  modifyPost: async (post: Post) => {
    const { data } = await baseInstance.put<{ message: string }>(`/posts/${post.id}`, { data: post });
    return data;
  },
  deletePost: async (postId: string) => {
    const { data } = await baseInstance.delete<{ message: string }>(`/posts/${postId}`);
    return data;
  },
};

export default postAPI;

위 코드에서 게시글을 등록하는 API인 addPost 로 예시를 들자면:

1. API URI 정의: /posts
2. API 요청 타입 정의: baseInstance.post의 데이터로 전달되는 인자 { data: post }
3. API 응답 타입 정의: 제네릭으로 전달되는 인자 { message: string }

이렇게 API에 연관 있는 핵심 정보를 관리하고 있어요
이 정보는 이후에 useQuery 나 useMutation 을 사용할 때에도 자동 추론하는 정보로 사용되어요!

컨벤션

• get??: 데이터 가져오는 함수 (GET)
• post??: 데이터 추가하는 함수 (POST)
• put??: 데이터 수정하는 함수 (PUT)
• delete??: 데이터 삭제하는 함수 (DELETE)

접두사는 이렇게 동작이 들어가게 하는 것 어떨까요!?

3. queryKey 매핑

tanstack-query가 데이터를 캐싱하고 패칭하는 함수에 대한 매핑 정보를 적어줘요.
아래는 /api/queries/posts.ts 예시예요.

import { createQueryKeys } from '@lukemorales/query-key-factory';
import postAPI from '../functions/postAPI';

const posts = createQueryKeys('posts', {
  all: {
    queryKey: null,
    queryFn: postAPI.fetchPosts,
    contextQueries: {
      odd: {
        queryKey: null,
        queryFn: postAPI.fetchPosts,
      },
    },
  },
  detail: (postId: string) => ({
    queryKey: [postId],
    queryFn: () => postAPI.fetchPostDetail(postId),
  }),
});

export default posts;

4. 공통화가 필요한 경우에는 커스텀 훅 정의

만약 query나 mutation에 공통 로직이나 공통 옵션을 사용해야 한다면, 이 부분은 훅으로 묶는 방법도 좋을 것 같아요!

예시 1. 홀수ID의 포스트 목록

공통 옵션이라던가, 홀수만 필터링하는 공통 로직을 묶어서 훅으로 작성했어요.
(좋은 예시인지는 모르겠네요! 캐싱된 데이터는 queryFn 자체의 반환값이긴 해서..)

import { useQuery } from '@tanstack/react-query';
import queryKeys from '../queryKeys';

const useOddPostQuery = (maxLength: number) => {
  const query = useQuery({
    ...queryKeys.posts.all._ctx.odd,
    retry: 2,
    gcTime: 1000 * 60 * 60 * 24,
  });

  const filteredData = query.data?.filter((post) => post.id % 2).slice(0, maxLength);

  return { ...query, data: filteredData };
};

export default useOddPostQuery;

컨벤션은 use~~Query() 로 접미사에 Query 를 붙히는 것 어떨까요?

예시 2. 게시글 수정에 낙관적 업데이트 적용

공식 문서 를 참고해서 예시 훅을 작성했어요.

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { Post } from '@/types';
import postAPI from '../functions/postAPI';
import queryKeys from '../queryKeys';

const useModifyPost = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: postAPI.modifyPost,
    onMutate: async (post) => {
      const { queryKey } = queryKeys.posts.detail(`${post.id}`);

      // 이미 Fetching 중인 데이터가 있다면 낙관적 업데이트로 미리 반영한 값을 덮어씌울 가능성이 있기에, cancel 합니다.
      await queryClient.cancelQueries(queryKeys.posts.detail(`${post.id}`));

      // 이전 데이터를 저장해둡니다.
      const previousPost = queryClient.getQueryData<Post>(queryKey);

      // 새로운 데이터를 미리 반영합니다.
      queryClient.setQueryData<Post>(queryKey, post);

      // 이전 데이터를 반환합니다. 이 값은 나중에 에러 발생시 데이터를 원상복구 하는데 사용됩니다.
      return { previousPost };
    },
    onError: (err, post, context) => {
      // 이전 데이터로 롤백합니다.
      queryClient.setQueryData<Post>(queryKeys.posts.detail(`${post.id}`).queryKey, context?.previousPost);
    },
    onSettled: () => {
      // 모든 포스트에 대한 쿼리를 업데이트합니다.
      queryClient.invalidateQueries(queryKeys.posts.all);
    },
  });
};

export default useModifyPost;

컨벤션은 mutationFn의 이름 앞에 use 만 붙인 형태로 하면 어떨까요?

5. 실제로 컴포넌트에서 사용

function App() {
  const { data: postList } = useQuery({ ...queryKeys.posts.all }); // 매핑된 queryKey 사용
  const { data: postDetail } = useQuery({ ...queryKeys.posts.detail('5') }); // 매핑된 queryKey 사용
  const { data: oddPostList } = useOddPostQuery(10); // 커스텀 훅 사용

  const { mutate: addPost } = useMutation({ mutationFn: postAPI.addPost }); // 정의된 API 함수 사용
  const { mutate: modifyPost } = useModifyPost(); // 커스텀 훅 사용

  const handleAddPost = () => {
    addPost({ id: 1, title: 'title', body: 'body', userId: 1 });
  };

  const handleModifyPost = () => {
    modifyPost({ id: 1, title: 'title', body: 'body', userId: 1 });
  };

  return (
    <div>
      <button onClick={handleAddPost}>게시글 추가 요청</button>
      <button onClick={handleModifyPost}>게시글 수정 요청</button>
    </div>
  );
}

요약

쓰다보니 너무 길어졌네요 ㅜㅜㅜ 죄송해요!!
요약하자면 레이어를 여러 개 놓고 공통 로직이 꼭 필요한 경우에만 커스텀 훅으로 빼자는 취지였습니다!!