DX & Quality · 피에프씨테크놀로지스
API 타입자판기
Orval 기반 API 연동 자동화OpenAPI 명세 하나로 fetch 함수·TanStack Query 훅·타입을 생성하는 Orval을 제안하고, 웹뷰 앱의 투자 화면에 먼저 세팅해 보여 준 뒤 웹 레포 전체의 표준 API 레이어로 확산시켰어요.
0개 앱
웹 레포 표준 API 레이어
0+
생성 operation
0파일
첫 적용 때 교체한 코드
BeforeAPI 하나마다 세 파일을 손으로
// types.ts — 명세를 보며 손으로
export interface Product {
id: number;
title: string;
rate: number; // 서버는 string 으로 바뀜 😢
}
// api.ts
export const getProducts = (params: Params) =>
client.get<Product[]>('/products', { params })
.then((res) => res.data);
// hooks.ts
export const useProducts = (params: Params) =>
useQuery({
queryKey: ['products', params],
queryFn: () => getProducts(params),
});After명세에서 만들어 쓰기만
// 명세가 바뀌면
$ pnpm generate:api
// 화면에서는 생성된 훅을 그대로
const { data } = useGetProducts(params);
// 타입이 어긋나면 빌드에서 먼저 터진다
data.rate.toFixed(2);
// ✕ 'string' 에는 'toFixed' 가 없어요01Problem
매 API마다 fetch 함수, TanStack Query 훅, 타입을 손으로 작성했어요. 더 큰 문제는 서버 API가 바뀌어도 클라이언트에 공유되지 않아, 타입이 실제 응답과 어긋난 채 흘러간다는 점이었습니다.
계기는 예약투자에서 보낸 요청 필드가 서버에 반영되지 않던 이슈였어요. 타입은 맞다고 했지만, 명세와 실제가 달랐어요.
단일 출처OpenAPI 명세서버가 쓰는 문서
→
스크립트 한 번Orval필요한 태그만 골라 생성
→
- 타입요청 · 응답 모양
- fetch 함수공통 axios 인스턴스로
- Query 훅queryKey 까지 생성
→
화면생성 코드를 쓰기만생성물은 고치지 않고, 필요하면 감싸는 훅을 따로
02What I built
- 먼저 세팅하고 규칙부터웹뷰 앱에 Orval을 세팅하면서 규칙을 먼저 정했어요. 생성된 코드는 절대 고치지 않고, 바꿔야 하면 감싸는 훅을 따로 만든다. 언제 감싸는 훅을 만들지, 무한 스크롤은 어떻게 쓰는지 같은 가이드 문서 다섯 개를 같이 올렸어요.
- 빌드에 묶었다가 다시 풀기처음엔 빌드할 때마다 명세를 새로 받아 생성하게 했어요. 늘 최신이라는 장점이 있었지만, 써 보니 서버가 아직 안 고친 명세가 빌드를 막고 의미 없는 변경이 쌓였어요. 장단점을 정리해 팀과 논의했고, 지금은 필요할 때 생성해서 커밋하고 PR에서 변경을 리뷰하는 방식이에요.
- 먼저 적용하고 공유투자 앱의 손 axios 호출을 생성 함수로 교체(97파일)하고, 적용기를 팀에 공유했어요.
- 명세 신뢰성적용하면서 명세에 없던 API를 찾아 서버에 문서화를 요청하고, 백엔드용 API 작성 가이드(Do & Don't) 중 투자 서버 몫을 작성했어요.
- 확산CTO 요청으로 웹 전면 도입이 결정되고, API 관리 회의에서 사례를 공유했어요.
03Result
- 웹 레포 6개 앱의 표준 API 레이어. 손으로 쓰던 API 호출을 대부분 생성 코드로 대체하고, 스펙이 바뀌면 재생성으로 타입을 맞춰요.
- 전사 OpenAPI 작성 정책 논의의 계기가 됐어요.
- 한계도 알고 있어요생성 코드라 infiniteQuery·커스텀 queryKey는 번거롭고, 재생성은 아직 사람이 실행해요. 생성할 수 없는 일부 API는 손으로 남겨 두었어요.
04Learning
도구 도입의 핵심은 도구가 아니라 그 도구가 기대는 데이터, 여기선 API 명세의 신뢰성이다. 도구를 들이는 비용보다, 협업 방식을 바꾸는 비용을 어떻게 설득하느냐가 진짜 무게였다.