현재 나는 '한세로' 라는 프로젝트를 진행 중이다.

한세로는 React Native(Expo) 환경으로 진행 중인 프로젝트이며, 한세대학교 학우분들을 위한 택시 카풀 매칭 앱 서비스이다.

학교 근처 역인 금정역과 산본역에서 학교까지 택시를 타고 싶지만, 혼자 부담하기에는 비싼 요금 때문에 망설이는 학우분들을 위해 기획되었다.

자동으로 같이 탈 사람을 매칭해 주어 비용 부담을 덜어주는 것이 이 서비스의 핵심이다.

이 프로젝트를 진행하면서, 왜 Orval을 도입하여 API 연동을 자동화했는지 그 고민에 대한 이야기를 작성하려고 한다.

1. 학습과 효율 사이에서의 결정

이 프로젝트 진행에 있어서 API 코드를 직접 작성 및 구현하는 방식으로 진행할 계획이었다.

물론 나도 프로젝트 경험이 많지 않지만, 다른 프론트 팀원들보다는 약간의 경험이 더 있기에 프로젝트 세팅부터 어쩌다보니 리드? 역할을 담당하게 되었다..

우리 프론트 팀원들은 정말 간단한 백엔드와의 연동을 진행한 경험이 한번 정도 경험한 분들이기에, API 함수 및 타입을 직접 타이핑하며 코드들이 어떻게 유기적으로 연결되는지 몸소 체험하면서 학습하는 방식을 지향하려고 했다.

하지만 냉정하게 상황을 생각했을 때, 아래와 같은 문제들을 고려하지 않을 수 없었다.

고려한 문제들

1. 3월 이전 마감이라는 타이트한 일정

   • 도구를 학습하고 에러를 해결하며 수동으로 코드를 짜기에는 시간이 부족할 것 같았다.

2. 불필요한 시간 낭비

   • 우리 서비스의 핵심은 WebSocket 방식을 이용하는 실시간 매칭과 채팅이다.

3. 현실적인 상황

   • 현재 프론트 개발 시장에서 Tanstack Query(React Query) 은 많은 채용 공고에서 필수 역량으로 요구하고 있다. 팀원들이 이번 프로젝트를 통해 이런 필수 역량에 해당하는 도구를 경험하게 해주고 싶었다.

결국, 팀원들이 단순 반복적인 보일러플레이트 작성에 많은 시간을 투자하는 것보다는, 현업 수준의 DX를 경험하며 효율적으로 기능을 구현할 수 있도록 Orval 라는 도구를 최종적으로 도입하기로 결정했다.

사실 이제 막 갓 졸업한 내가 "현업 수준의 DX" 라는 문장을 사용하는게 적절한 지는 모르겠다. 하하,,

2. Tanstack Query(TQ) && Orval

우리 프로젝트는 실시간 기능을 위해 WebSocket을 사용하지만, 여전히 다른 기능과 연결되는 일반적인 데이터는 rest api 방식으로 통신을 하게 된다. 이때 Orval 라는 도구는 우리에게 단순한 도구 이상의 가치를 가져올 수 있다고 판단했다.

Orval 도입의 가치

1. 코드 리뷰 시간 확보

   • Orval 을 활용하게 되면 API 연동 시간을 획기적으로 줄일 수 있다. 이렇게 확보된 시간은 각자의 코드를 리뷰하고, 어떻게 하면 더 좋은 코드로 개선할 수 있을 지 토론하는데 시간을 할애할 수 있다.

2. UI, UX 그리고 DX 까지

   • TQ가 제공하는 캐싱기능, 로딩/에러 핸들링은 사용자와 개발자 모두에게 쾌적한 경험을 제공해준다.
   • Orval은 이 코드를 자동으로 생성해 주어 팀원 모두가 수준 높은 비동기 처리를 구현할 수 있게 돕는다.

3. 타입 안정성

   • 서버 명세가 바뀌면 명령어 한 줄로 프론트엔드 타입까지 업데이트된다.
   • 이는 오타나 타입 불일치로 인한 소모적인 디버깅 시간을 제거하여 휴면 에러를 방지할 수 있다.

3. Orval 설정 파일 구성하기

우리 프로젝트에서 사용하는 orval.config.ts 파일이다. 팀원들이 각 옵션의 의미를 알 수 있도록 정리했다.

import { defineConfig } from 'orval';

export default defineConfig({
  hanseiroApi: {
    input: {
      target: 'BACKEND API URL', // 백엔드 API 명세 주소, 추후 추가 예정
    },
    output: {
      mode: 'tags-split', // API 그룹별로 파일을 나눠 관리
      target: './src/api/generated', // 코드가 생성될 위치
      client: 'react-query', // React Query 훅 생성
      httpClient: 'axios',
      schemas: './src/api/generated/model', // 타입 정의 저장 위치
      override: {
        mutator: {
          // 공통 인증 로직이 담긴 커스텀 axios 인스턴스 사용
          path: './src/shared/lib/axios.ts',
          name: 'customInstance',
        },
        query: {
          useQuery: true,
          useMutation: true,
          version: 5, // React Query v5 적용
        },
      },
    },
  },
});

터미널에서 yarn api:generate 명령어를 실행하면 API 관련 코드가 자동으로 생성된다.

4. 간단한 예시 코드

Orval을 도입하면 개발 방식이 아래와 같이 바뀐다.
전에는 수십 줄씩 짜야 했던 코드가 단 한 줄로 끝난다.

// Orval이 자동으로 만들어준 훅을 가져와서 사용한다.
import { useGetMe } from '../api/generated/user/user';

const MyProfile = () => {
  // 로딩, 에러, 데이터 상태를 React Query가 관리하고 Orval이 훅으로 제공한다.
  const { data, isLoading, isError } = useGetMe();

  if (isLoading) return <Text>프로필 로딩 중...</Text>;
  if (isError) return <Text>데이터를 불러오지 못했습니다.</Text>;

  return (
    <View>
      <Text>환영합니다, {data?.name}님!</Text>
    </View>
  );
};

마치며

직접 모든 코드를 짜보며 배우는 경험도 중요하지만, 현대적인 도구를 활용해 프로젝트의 오나성도를 높이고 확보된 시간에 더 가지 있는 고민을 하는 능력 또한 개발자에게 필요한 역량이라고 생각한다.

Orval이 생성해준 코드는 그 자체로 훌륭한 교과서가 될 것 같다.

이 구조를 분석하고 우리만의 코드 리뷰 문화로, 단순히 코드를 작성하고 기능을 구현하는 것을 넘어서 팀원과 나 또한 좋은 코드를 쓰는 개발자로 성장했으면 좋겠다.