07 비동기 호출
7.1 API 요청
1. fetch로 API 요청하기
신입 개발자인 배달이는 사용자가 장바구니를 조회해서 볼 수 있는 기능을 만들게 되었다.
그래서 외부 데이터베이스에 접근하여 사용자가 장바구니에 추가한 정보를 호출하는 코드를 작성했는데 직접 fetch 함수를 사용해서 사용자가 담은 장바구니 물품 개수를 배지로 멋지게 보이게 했다.
import React, { useEffect, useState } from 'react'
const CartBadge: React.FC = () => {
const [cartCount, setCartCount] = useState(0)
useEffect(() => {
fetch('https://api.baemain.com/cart')
.then((response) => response.json())
.then(({ cartItem }) => {
setCartCount(cartItem.length)
})
}, [])
return <>{/* cartCount 상태를 이용하여 컴포넌트 렌더링 */}</>
}
장바구니 정보를 비동기 함수인 fetch로 불러와 장바구니 내부를 확인하여 장바구니에 담긴 물품의 개수를 배지 아이콘으로 보여주는 기능, 사용자에게 장바구니에 담은 물품을 보여주는 페이지 구현 등 여러 곳에서 같은 API URL을 복붙하여 사용하게 되었다.
그런데 백엔드에서 기능 변경을 해야 해서 API URL을 수정해야 한다고 한다.
아쉽게도 이미 컴포넌트 내부에 깊숙이 자리 잡은 비동기 호출 코드는 이러한 변경 요구에 취약하다.
비단 URL 변경뿐 아니라 ‘여러 서버에 API를 요청할 때 타임아웃 설정이 필요하다’ 또는 ‘모든 요청에 커스텀 헤더가 필요하다’ 같은 새로운 API 요청 정책이 추가될 때마다 계속해서 비동기 호출 코드를 수정해야 하는 번거로움이 발생한다.
2. 서비스 레이어로 분리하기
여러 API 요청 정책이 추가되어 코드가 변경될 수 있다는 것을 감안한다면, 비동기 호출 코드는 컴포넌트 영역에서 분리되어 다른 영역(서비스 레이어)에서 처리되어야 한다.
앞의 코드를 기준으로 설명하면 fetch 함수를 호출하는 부분이 서비스 레이어로 이동하고, 컴포넌트는 서비스 레이어의 비동기 함수를 호출하여 그 결과를 받아와 렌더링하는 흐름이 된다.
그러나 단순히 fetch 함수를 분리하는 것만으로는 API 요청 정책이 추가되는 것을 해결하기 어렵다.
예를 들어 fetch 함수에서 타임아웃을 설정하기 위해서는 다음과 같이 구현해야 한다.
async function fetchCart() {
const controller = new AbortController()
const timeoutId = setTimeout(() => controller.abort(), 5000)
const response = await fetch('https://api.baemain.com/cart', {
signal: controller.signal,
})
clearTimeout(timeoutId)
return response
}
또한 쿼리 매개변수(query parameter)나 커스텀 헤더 추가 또는 쿠키를 읽어 토큰을 집어넣는 등 다양한 API 정책이 추가될 수 있는데 이를 모두 구현하는 것은 번거로운 일이다.
3. Axios 활용하기
fetch는 내장 라이브러리이기 때문에 따로 임포트하거나 설치할 필요 없이 사용할 수 있다.
그러나 많은 기능을 사용하려면 직접 구현해서 사용해야 한다.
이러한 번거로움 때문에 fetch 함수를 직접 쓰는 대신 Axios 라이브러리를 사용하고 있다.
const apiRequester: AxiosInstance = axios.create({
baseURL: 'https://api.baemain.com/cart',
timeout: 5000,
})
const fetchCart = (): AxiosPromise<FetchCartResponse> =>
apiRequester.get<FetchCartResponse>('cart')
const postCart = (postCartRequest: PostCartRequest): AxiosPromise<PostCartResponse> =>
apiRequester.post<PostCartResponse>('cart', postCartRequest)
각 서버(주문을 처리하는 서버와 장바구니를 처리하는 서버)가 담당하는 부분이 다르거나 새로운 프로젝트의 일부로 포함될 때 기존에 사용하는 API Entry(Base URL)와는 다른 새로운 URL로 요청해야 하는 상황이 생길 수 있다.
이렇게 API Entry가 2개 이상일 경우에는 각 서버의 기본 URL을 호출하도록 orderApiRequester, orderCartApiRequester같이 2개 이상의 API 요청을 처리하는 인스턴스를 따로 구성해야 한다.
이후 다른 URL로 서비스 코드를 호출할 때는 각각의 apiRequester를 사용하면 된다.
const apiRequester: AxiosInstance = axios.create(defaultConfig)
const orderApiRequester: AxiosInstance = axios.create({
baseURL: 'https://api.baemin.or/',
...defaultConfig,
})
const orderCartApiRequester: AxiosInstance = axios.create({
baseURL: 'https://cart.baemin.order/',
...defaultConfig,
})
4. Axios 인터셉터 사용하기
각각의 requester는 서로 다른 역할을 담당하는 다른 서버이기 때문에 requester별로 다른 헤더를 설정해줘야 하는 로직이 필요할 수도 있다.
이때 인터셉터 기능을 사용하여 requester에 따라 비동기 호출 내용을 추가해서 처리할 수 있다.
또한 API 에러를 처리할 때 하나의 에러 객체로 묶어서 처리할 수도 있다.
import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
const getUserToken = () => ''
const getAgent = () => ''
const getOrderClientToken = () => ''
const orderApiBaseUrl = ''
const orderCartApiBaseUrl = ''
const defaultConfig = {}
const httpErrorHandler = () => {}
const apiRequester: AxiosInstance = axios.create({
baseURL: 'https://api.baemin.com',
timeout: 5000,
})
const setRequestDefaultHeader = (requestConfig: AxiosRequestConfig) => {
const config = requestConfig
config.headers = {
...config.headers,
'Content-Type': 'application/json;charset=utf-8',
user: getUserToken(),
agent: getAgent(),
}
return config
}
const setOrderRequestDefaultHeader = (requestConfig: AxiosRequestConfig) => {
const config = requestConfig
config.headers = {
...config.headers,
'Content-Type': 'application/json;charset=utf-8',
'order-client': getOrderClientToken(),
}
return config
}
// `interceptors` 기능을 사용해 header를 설정하는 기능을 넣거나 에러를 처리할 수 있다
apiRequester.interceptors.request.use(setRequestDefaultHeader)
const orderApiRequester: AxiosInstance = axios.create({
baseURL: orderApiBaseUrl,
...defaultConfig,
})
// 기본 apiRequester와는 다른 header를 설정하는 `interceptors`
orderApiRequester.interceptors.request.use(setOrderRequestDefaultHeader)
// `interceptors`를 사용해 httpError 같은 API 에러를 처리할 수도 있다
orderApiRequester.interceptors.response.use(
(response: AxiosResponse) => response,
httpErrorHandler
)
const orderCartApiRequester: AxiosInstance = axios.create({
baseURL: orderCartApiBaseUrl,
...defaultConfig,
})
orderCartApiRequester.interceptors.request.use(setRequestDefaultHeader)
이와 달리 요청 옵션에 따라 다른 인터셉터를 만들기 위해 빌더 패턴을 추가하여 APIBuilder 같은 클래스 형태로 구성하기도 한다.
class API {
readonly method: HTTPMethod;
readonly url: string;
baseURL?: string;
headers?: HTTPHeaders;
params?: HTTPParams;
data?: unknown;
timeout?: number;
withCredentials?: boolean;
constructor(method: HTTPMethod, url: string) {
this.method = method
this.url = url
}
call<T>(): AxiosPromise<T> {
const http = axios.create()
// 만약 `withCredential`이 설정된 API라면 아래 같이 인터셉터를 추가하고, 아니라면 인터셉터를 사용하지 않음
if (this.withCredentials) {
http.interceptors.response.use(
response => response,
error => {
if (error.response && error.reponse.status === 401) {
/* 에러 처리 진행 */
}
return Promise.reject(error)
}
)
}
return http.request({ ...this })
}
}
이처럼 기본 API 클래스로 실제 호출 부분을 구성하고, 위와 같은 API를 호출하기 위한 래퍼(Wrapper)를 빌더 패턴으로 만든다.
class APIBuilder {
private _instance: API;
constructor(method: HTTPMethod, url: string, data?: unknown) {
this._instance = new API(method, url)
this._instance.baseURL = apiHost
this._instance.data = data
this._instance.headers = {
'Content-Type': 'application/json; charset=utf-8',
}
this._instance.timeout = 5000
this._instance.withCredentials = false
}
static get = (url: string) => new APIBuilder('GET', url)
static put = (url: string, data: unknown) => new APIBuilder('PUT', url, data)
static post = (url: string, data: unknown) => new APIBuilder('POST', url, data)
static delete = (url: string) => new APIBuilder('DELETE', url)
baseURL(value: string): APIBuilder {
this._instance.baseURL = value
return this
}
headers(value: HTTPHeaders): APIBuilder {
this._instance.headers = value
return this
}
timeout(value: number): APIBuilder {
this._instance.timeout = value
return this
}
params(value: HTTPParams): APIBuilder {
this._instance.params = value
return this
}
data(value: unknown): APIBuilder {
this._instance.data = value
return this
}
withCredentials(value: boolean): APIBuilder {
this._instance.withCredentials = value
return this
}
build(): API {
return this._instance
}
}
이와 같은 패턴으로 제공한 APIBuilder를 사용하는 코드는 다음과 같다.
const fetchJobNameList = async (name?: string, size?: number) => {
const api = APIBuilder.get('/apis/web/jobs')
.withCredentials(true) // 이제 401 에러가 나는 경우, 자동으로 에러를 탐지하는 인터셉터를 사용하게 된다
.params({ name, size }) // body가 없는 axios 객체도 빌더 패턴으로 쉽게 만들 수 있다
.build();
const { data } = await api.call<Response<JobNameListResponse>>();
return data;
}
APIBuilder 클래스는 보일러플레이트 코드가 많다는 단점을 갖고 있다.
하지만 옵션이 다양한 경우에 인터셉터를 설정값에 따라 적용하고, 필요 없는 인터셉터를 선택적으로 사용할 수 있다는 장점도 갖고 있다.
보일러플레이트(boilerplate) 코드
어떤 기능을 사용할 때 반복적으로 사용되는 기본적인 코드를 말한다.
예를 들어 API를 호출하기 위한 기본적인 설정과 인터셉터 등을 설정하는 부분을 보일러플레이트 코드로 간주할 수 있다.
5. API 응답 타입 지정하기
같은 서버에서 오는 응답의 형태는 대체로 통일되어 있어서 앞서 소개한 API의 응답 값은 하나의 Response 타입으로 묶일 수 있다.
interface Response<T> {
data: T;
status: string;
serverDateTime: string;
errorCode?: string; // FAIL, ERROR
errorMessage?: string; // FAIL, ERROR
}
const fetchCart = (): AxiosPromise<Response<FetchCartResponse>> =>
apiRequester.get<Response<FetchCartResponse>>('cart');
const postCart = (postCartRequest: PostCartRequest): AxiosPromise<Response<PostCartResponse>> =>
apiRequester.post<Response<PostCartResponse>>('cart', postCartRequest);
이와 같이 서버에서 오는 응답을 통일해줄 때 주의할 점이 있다.
Response 타입을 apiRequester 내에서 처리하고 싶은 생각이 들 수 있는데, 이렇게 하면 UPDATE나 CREATE같이 응답이 없을 수 있는 API를 처리하기 까다로워진다.
따라서 Response 타입은 apiRequester가 모르게 관리되어야 한다.
API 요청 및 응답 값 중에서는 하나의 API 서버에서 다른 API 서버로 넘겨주기만 하는 값도 존재할 수 있다.
해당 값에 어떤 응답이 들어있는지 알 수 없거나 값의 형식이 달라지더라도 로직에 영향을 주지 않는 경우에는 unknown 타입을 사용하여 알 수 없는 값임을 표현한다.
interface response {
data: {
cartItems: CartItem[];
forPass: unknown;
}
}
만약 forPass 안에 프론트 로직에서 사용해야 하는 값이 있다면, 여전히 어떤 값이 들어올지 모르는 상태이기 때문에 unknown을 유지한다.
로그를 위해 단순히 받아서 넘겨주는 값의 타입은 언제든지 변경될 수 있으므로 forPass 내의 값을 사용하지 않아야 한다.
다만 이미 설계된 프로덕트에서 쓰고 있는 값이라면 프론트 로직에서 써야 하는 값에 대해서만 타입을 선언한 다음에 사용하는 게 좋다.
type ForPass = {
type: 'A' | 'B' | 'C'
}
const isTargetValue = () => (data.forPass as ForPass).type === 'A'
6. 뷰 모델(View Model) 사용하기
API 응답은 변할 가능성이 크다.
특히 새로운 프로젝트는 서버 스펙이 자주 바뀌기 때문에 뷰 모델을 사용하여 API 변경에 따른 범위를 한정해줘야 한다.
특정 객체 리스트를 조회하여 리스트 각각의 내용과 리스트 전체 길이 등을 보여줘야 하는 화면을 떠올려보자.
해당 리스트를 조회하는 fetchList API는 다음처럼 구성될 것이다.
interface ListResponse {
items: ListItem[];
}
const fetchList = async (filter?: ListFetchFilter): Promise<ListResponse> => {
const { data } = await api
.params({ ...filter })
.get('/apis/get-list-summaries')
.call<Response<ListResponse>>()
return { data }
}
해당 API를 사용할 때는 다음처럼 사용한다.
이 예시에서는 컴포넌트 내부에서 비동기 함수를 호출하고 then으로 처리하고 있지만, 실제 비동기 함수는 컴포넌트 내부에서 직접 호출되지 않는다.
const ListPage: React.FC = () => {
const [totalItemCount, setTotalItemCount] = useState(0)
const [items, setItems] = useState<ListItem[]>([])
useEffect(() => {
// 예시를 위한 API 호출과 then 구문
fetchList(filter).then(({ items }) => {
setCartCount(items.length)
setItems(items)
})
}, [])
return (
<div>
<Chip label={totalItemCount} />
<Table items={items} />
</div>
)
}
흔히 좋은 컴포넌트는 변경될 이유가 하나뿐인 컴포넌트라고 말한다.
API 응답의 items 인자를 좀 더 정확한 개념으로 나타내기 위해 jobItems나 cartItems 같은 이름으로 수정하면 해당 컴포넌트도 수정해야 한다.
이렇게 수정해야 할 컴포넌트가 API 1개에 하나라면 좋겠지만, API를 사용하는 기존 컴포넌트도 수정되어야 한다.
보통 이런 상황이 프로젝트 초기에 자주 발생하곤 한다.
이러한 문제를 해결하기 위한 방법으로 뷰 모델을 도입할 수 있다.
// 기존 ListResponse에 더 자세한 의미를 담기 위한 변화
interface JobListItemResponse {
name: string;
}
interface JobListResponse {
jobItems: JobListItemResponse[];
}
class JobList {
readonly totalItemCount: number;
readonly items: JobListItemResponse[];
constructor({ jobItems }: JobListResponse) {
this.totalItemCount = jobItems.length;
this.items = jobItems;
}
}
const fetchJobList = async (filter?: ListFetchFilter): Promise<JobListResponse> => {
const { data } = await api
.params({ ...filter })
.get('/apis/get-list-summaries')
.call<Response<JobListResponse>>();
return new JobList(data);
};
뷰 모델을 만들면 API 응답이 바뀌어도 UI가 깨지지 않게 개발할 수 있다.
또한 앞의 예시처럼 API 응답에는 없는 totalItemCount 같은 도메인 개념을 넣을 때 백엔드나 UI에서 로직을 추가하여 처리할 필요 없이 간편하게 새로운 필드를 뷰 모델에 추가할 수 있다.
그러나 뷰 모델 방식에서도 문제가 발생할 수 있다.
추상화 레이어 추가는 결국 코드를 복잡하게 만들며 레이어를 관리하고 개발하는 데도 비용이 든다.
결국 API 응답이 바뀌었을 때는 클라이언트 코드를 수정하는 데 들어가는 비용을 줄이면서도 도메인의 일관성을 지킬 수 있는 절충안을 찾아야 한다.
꼭 필요한 곳에만 뷰 모델을 부분적으로 만들어서 사용하기, 백엔드와 클라이언트 개발자가 충분히 소통한 다음에 개발하여 API 응답 변화를 최대한 줄이기, 뷰 모델에 필드를 추가하는 대신에 getter 등의 함수를 추가하여 실제 어떤 값이 뷰 모델에 추가한 값인지 알기 쉽게 하기 등의 방법을 예로 들 수 있다.
개발 단계에서는 API 응답 형식이 자주 바뀐다.
또한 응답 값의 타입이 string이어야 하는데 number가 들어오는 것과 같이 잘못된 타입이 전달되기도 한다.
그러나 타입스크립트는 정적 검사 도구로 런타임에서 발생하는 오류는 찾아낼 수 없다.
런타임에 API 응답의 타입 오류를 방지하려면 Superstruct 같은 라이브러리를 사용하면 된다.
7. Superstruct를 사용해 런타임에서 응답 타입 검증하기
런타임 응답 타입 검증을 하기 위해 사용하는 Superstrct 라이브러리의 소개를 찾아보면 아래와 같이 설명하고 있다.
- Superstruct를 사용하여 인터페이스 정의와 자바스크립트 데이터의 유효성 검사를 쉽게 할 수 있다.
- Superstruct는 런타임에서의 데이터 유효성 검사를 통해 개발자와 사용자에게 자세한 런타임 에러를 보여주기 위해 고안되었다.
공식 문서에서 제공하는 간단한 코드 예시는 아래와 같다.
import { assert, is, validate, object, number, string, array } from 'superstruct'
const Article = object({
id: number(),
title: string(),
tags: array(string()),
author: object({
id: number(),
}),
})
const data = {
id: 34,
title: 'Hello World',
tags: ['news', 'features'],
author: {
id: 1,
},
}
assert(data, Article)
is(data, Article)
validate(data, Article)
먼저 Article이라는 변수는 Superstruct의 object() 모듈의 반환 결과다.
object()라는 모듈 이름에서 예상할 수 있듯이 Article은 object(객체) 형태를 가진 무언가라고 생각할 수 있다.
실제 Superstruct 내부 로직에서 반환되는 타입은 object()의 반환 결과를 한 번 더 감싸서 내려온다.
그렇다면 number(), string() 모듈의 반환 타입도 숫자, 문자열 형태라고 이해할 수 있다.
Article의 id는 숫자, title은 문자열, tags는 문자열 배열, author는 id라는 숫자를 속성으로 가진 객체 형태의 object이다.
즉, 위와 같은 데이터 명세를 가진 스키마이다.
data라는 변수는 보는 그대로 어떤 데이터 정보를 담은 object를 가리키고 있다.
그렇다면 assert, is, validate라는 모듈은 무엇일까?
각각 ‘확인’, ‘~이다’, ‘검사하다’ 정도로 직역할 수 있는데 3가지 모두 데이터의 유효성 검사를 도와주는 모듈이다.
세 모듈의 공통점은 데이터 정보를 담은 data 변수와 데이터 명세를 가진 스키마인 Article을 인자로 받아 데이터가 스키마와 부합하는지를 검사한다는 것이다.
차이점은 모듈마다 데이터의 유효성을 다르게 접근하고 반환 값 형태가 다르다는 것이다.
- assert는 유효하지 않을 경우 에러를 던진다.
- is는 유효성 검사 결과에 따라 true 또는 false 즉, boolean 값을 반환한다.
- validate는 [error, data] 형식의 튜플을 반환한다. 유효하지 않은 때는 에러 값이 반환되고 유효한 경우에는 첫 번째 요소로 undefined, 두 번째 요소로 data value가 반환된다.
지금까지 SuperStruct의 공식 문서를 참조하여 런타임에서의 자바스크립트 데이터의 유효성 검사가 실행되는 구조를 살펴봤다.
그렇다면 타입스크립트와는 어떤 시너지를 발휘할 수 있는지 알아보자.
먼저 아래와 같이 Infer를 사용하여 기존 타입 선언 방식과 동일하게 타입을 선언할 수 있다.
import { Infer, number, object, string } from 'superstruct'
const User = object({
id: number(),
email: string(),
name: string(),
})
type User = Infer<typeof User>
앞의 type User는 기존의 타입스크립트 문법으로 작성되었다.
type User = {
id: number;
email: string;
name: string;
}
import { assert } from 'superstruct'
function isUser(user: User) {
assert(user, User)
console.log('적절한 유저입니다.')
}
앞의 예시는 Superstruct의 assert 메서드를 통해 인자로 받는 user가 User 타입과 매칭되는지 확인하는 isUser 함수이다.
const user_A = {
id: 4,
email: 'test@woowahan.email',
name: 'woowa',
}
isUser(user_A)
앞 코드를 실행하면 성공적으로 “적절한 유저입니다.”가 출력된다.
반면 아래 같이 기대하던 데이터 형식과 달리 런타임에 데이터가 오염되어 들어왔을 때는 어떻게 될까?
const user_B = {
id: 5,
email: 'wrong@woowahan.email',
name: 4,
}
isUser(user_B)
// error TS2345: Argument of type '{ id: number; email: string; name: number }' is not assignable to parameter of type '{ id: number; email: string; name: string }'
위와 같이 런타임 에러가 발생한다.
이처럼 컴파일 단계가 아닌 런타임에서도 적절한 데이터인지를 확인하는 검사가 필요할 때 유용하게 사용할 수 있다.
8. 실제 API 응답 시의 Superstruct 활용 사례
Superstruct의 개념과 사용법에 대해 간략하게 살펴보았다.
이제 API 응답 시 활용되는 방법을 예시로 살펴보자.
앞선 예시에서 본 fetchList 함수를 사용해보자.
fetchList의 호출 결과는 ListItem 타입의 배열이다.
여기에서는 ListItem 타입이 다음과 같다고 가정해보자.
interface ListItem {
id: string;
content: string;
}
interface ListResponse {
items: ListItem[]
}
const fetchList = async (filter?: ListFetchFilter): Promise<ListResponse> => {
const { data } = await api
.params({ ...filter })
.get('/apis/get-list-summaries')
.call<Response<ListResponse>>()
return { data }
}
우리는 fetchList 함수를 호출했을 때 id와 content가 담긴 ListItem 타입의 배열이 오기를 기대한다.
타입스크립트로 작성한 코드는 명시한 타입대로 응답이 올 거라고 기대하고 있지만 실제 서버 응답 형식은 다를 수 있다.
타입스크립트는 컴파일타임에 타입을 검증하는 역할을 한다.
따라서 타입스크립트만으로는 실제 서버 응답의 형식과 명시한 타입이 일치하는지를 확인할 수 없다.
이때 Superstruct를 활용하여 타입스크립트로 선언한 타입과 실제 런타임에서의 데이터 응답값을 매칭하여 유효성 검사를 할 수 있다.
먼저 Superstruct의 모듈을 사용하여 검증하는 코드를 아래 같이 작성해보자.
import { assert } from 'superstruct'
function isListItem(listItems: ListItem[]) {
listItems.forEach((listItem) => assert(listItem, ListItem))
}
isListItem은 ListItem의 배열 목록을 받아와 데이터가 ListItem 타입과 동일한지 확인하고 다를 경우에는 에러를 던진다.
이제 fetchList 함수에 Superstruct로 작성한 검증 함수를 추가하면 런타임 유효성 검사를 진행할 수 있게 된다.