🗳️Code Style

apis 폴더 내에 각 항목별 설명입니다.

1. type

1-1. DTO (Data Transfer Object)

data transfer object 의 줄임말로, 데이터 교환하기 위한 객체들을 뜻합니다.

저희 컨벤션에서는 api request 시 전달하는 parameter 의 타입을 정의하기 위해 사용됩니다.

DTO는 객체 형태로 선언한 타입을 사용합니다. 이를 사용하는 React Query 에서 parameter 가 1개 이하여아 올바른 타입 정의가 가능합니다.

각 파일 별로 하나의 타입만 정의하며, 추가로 필요한 타입은 import 하여 사용합니다.

1-2. Model

model 은 보통 서버에서 관리하는 데이터들을 의미합니다.

저희 컨벤션에서는 api response 시 전달받는 타입을 정의하기 위해 사용됩니다.

model 역시 파일 별로 하나의 타입만 정의해야 합니다.

DTO와 Model 타입 모두 얼마든지 선언 해도 좋지만 pagination, Promise 같은 공통적으로 사용하는 타입은 api 파일 안에서 generic 과 같은 형식으로 확장해서 사용하는걸 권장합니다.

좀 더 자세한 사용법은 아래 api 에서 확인해주세요.

2. Api

api 파일은 아래와 같은 code style을 갖고 있습니다.

gen:api 로 생성된 파일 또한 같은 규칙이니 컨벤션을 안다면 코드 해석이 더 쉬워집니다.

api 파일은 하나의 Class 로 만듭니다.
다른 추가 설정이 없다면 config에 설정된 axios instance 코드를 사용하며 다른 설정이 필요할 경우 파일 하단의 api 인스턴스 생성시, 새로운 axios instance를 주입하여 사용합니다.
.env 파일이나 배포시 환경변수로 base url 을 설정하기 때문에 url 에는 end point 만 적어주며, method 는 전부 대문자로 작성합니다.
parameter 와 return 타입은 dto / model 에서 선언한 타입들을 활용하여 꼭 명시해주세요.
호출한 데이터 사용 및 문제 파악에 용이합니다.
각 method의 명칭은 꼭 의미를 이해하기 쉽게 작성해주세요. 아래는 주로 사용하는 관행적인 규칙입니다.

GET -> get
POST -> create 등
PATCH, PUT -> update
DELETE -> delete

3. React Query

현재 axios와 더불어 편리한 데이터 관리를 위해 주로 React Query를 사용합니다.

각 ~api.ts 에서 생성한 method를 두 파일에 미리 custom hooks 형태로 작성한 후 사용합니다.

3-1. api.query.ts

api의 GET 메소드는 이 파일에 작성합니다. 미리 작성한 api 파일 뒤에 .query.ts 를 붙여 파일을 생성해주세요.

Query Key 선언

객체와 객체의 key 는 상수와 동일한 스타일로 작성해주세요.
query-key 함수의 인자는 api method 와 동일한 인자를 작성합니다. 예제와 같은 방법으로 유틸리티 함수인 Parameter 를 사용하면 api method 의 파라미터 타입을 반환합니다.
return 문은 배열로 작성하며 첫 번째는 query-key 문자열, 두번째는 인자로 넘긴 params 를 그대로 전달합니다. 인자가 없을 경우에는 .filter(isNotNull) 메서드가 params 를 제거합니다.

Custom Hooks 선언 이제 각 api method 별로 useQuery 를 생성합니다.

우측의 태그별로 하나씩 설명하겠습니다.

Naming

아래와 같은 규칙으로 네이밍을 붙여줍니다. 사용하는 api method의 의미를 표현하도록 작성합니다.

Params

생성할 api method의 parameter 타입을 정의합니다.

미리 생성된 유틸리티 타입 UseQueryParams 을 사용하여 generic 형태로 typeof api.method 를 전달하면 variables과 options 타입을 정의해줍니다.

variables 와 options 은 뭔가요? 추후 React Query를 사용하기 위한 parameter 라고 보면 됩니다. variables 은 앞서 dto 에서 선언한 request 인자들을 전달하면 되고 options 는 React Query hooks의 이벤트나 상태를 제어할 수 있습니다.

Query Key

상단에서 선언한 QUERY_KEY 함수에 params?.variables 을 인자로 넣어 생성합니다.

useQuery

사용하는 api method에 맞게 useQuery useInfiniteQuery 둘 중 하나를 반환합니다. 반환한 hooks 모두 query key를 비롯한 3개의 인자를 전달해야 합니다.

Query Fn

api method를 callback 함수 형태로 전달합니다.

options

해당 hooks를 사용하는 시점에서 options를 자유롭게 제어하기 위해 params?.options 을 그대로 전달합니다.

useInfiniteQuery 사용하기
useInfiniteQuery 를 사용하기 위해선 Query Fn 과 options 에서 추가적인 설정이 필요합니다.
Query Fn
queryFn 에서 인자로 제공하는 pageParam 을 다음 page를 받아오기 위한 인자로 전달합니다. default 값은 null 로 설정하면 첫 API 호출이 문제없이 작동합니다.
options
현재 페이지가 마지막인지 검사하는 기능인 getNextPageParam 이벤트를 params?.options 와 함께 전달합니다.

Query Key 사용

query-key 를 함수 형태로 작성했기 때문에 함수를 호출하는 방식으로 사용합니다.
사용한 인자를 전달하여 특정 query-key를 가져올 수 있습니다.
자세한 query-key 의 활용법은 React Query 공식문서 를 참고해주세요.

Custom Hooks 사용

사용법은 어렵지 않습니다. 앞서 선언만 잘 해주었다면 원하는 상황에 맞게 variables 와 options 를 사용하면 됩니다.

웬만하면 React Query 에서 반환하는 상태와 함수의 이름을 변경하여 사용합니다. 어떤 데이터인지 명확하게 파악하기 위함입니다.

InfiniteQuery 는 추가적인 설정이 필요합니다.

React Query 에서 관리하는 InfiniteQuery는 2차원 배열의 형태로 관리됩니다. 때문에 보통 2차원 배열을 flatMap 메서드로 풀어 1차원 배열로 가공 후 사용합니다.
다음 페이지를 받아올 때는 InfiniteQuery 에서 반환하는 fetchNextPage 함수를 사용합니다.
api 호출시 불필요한 요청을 막기 위해 hasNextPage isFetchingNextPage 두 상태를 활용하여 무한스크를의 조건을 걸어 사용합니다.

3-2. api.mutation.ts

api의 GET 을 제외한 메소드는 이 파일에 작성합니다. 미리 작성한 api 파일 뒤에 .mutation.ts 를 붙여 파일을 생성해주세요.

mutate.ts 의 선언은 위 query.ts 와 거의 동일합니다. 오히려 api method 에 관계 없이 useMutation 만 사용하기 때문에 더 쉽게 느껴질 수도 있습니다.

UseMutationParams 사용 등 일부만 다르니 천천히 비교하며 확인해보세요.

사용 부분 또한 간단합니다.

custom mutation 을 할당할 때 필요한 options 를 전달합니다.
api를 호출하기 위한 함수는 반환하는 mutate 함수를 사용합니다. 필요한 인자가 있다면 mutate 안에서 전달합니다.

이 외에 필요한 useMutation 공식문서 를 참고해주세요.

tokplate에서 Custom Hooks를 사용할 때 제네릭 타입을 선언하여 사용하고 있습니다.

- UseQueryParams
- UseInfiniteQueryParams
- UseMutationParams

해당 타입에 관한 설명은 
Convention/Types/modules/3.react-query 섹션에서 살펴봐주세요.

PreviousStructure NextComponents

Last updated 1 year ago