이 시리즈의 첫 글에서 “코드를 쓰기 전에 OpenAPI 계약부터 합의하자"는 이야기를 했습니다. 이번 글은 그 계약이 실제로 본전을 뽑게 해주는 도구에 대한 이야기입니다.

프론트엔드의 API 계층을 손으로 짜는 건, 즐겁다고 말하는 사람을 본 적이 없는 종류의 일입니다. 백엔드 문서에서 타입을 베껴 적고, 마흔 번째 똑같은 요청 래퍼를 쓰고, 3주 뒤에 누군가 필드명을 바꾸면 호출의 절반이 조용히 깨지죠. Orval은 이 일 자체를 없애줍니다. OpenAPI 스펙을 가리키기만 하면 클라이언트 코드를 생성해줍니다. 모든 엔드포인트에 대한 타입이 잡힌 함수, 계약과 정확히 일치하는 모델, 그리고 백엔드가 존재하기도 전에 개발에 쓸 수 있는 목(mock)까지.

프론트엔드 팀이 좋아하는 이유

#

목 생성이 은근히 저평가된 부분입니다. 스펙만 합의되면 프론트엔드는 가짜 서버를 띄워놓고 UI 전체를 거기에 대고 만들 수 있습니다. 영원히 “거의 다 됐어요” 상태인 엔드포인트를 기다릴 필요가 없죠. 진짜 백엔드가 나오면 클라이언트의 방향만 돌려주면 대부분 그대로 동작합니다. 양쪽이 같은 문서에서 만들어졌으니까요.

또 하나의 수확은, 지루한 코드가 구조적으로 올바르게 나온다는 점입니다. 손으로 짠 요청 바디에서 필드명을 잘못 치는 사람이 없어집니다. 애초에 손으로 요청 바디를 짜는 사람이 없어졌으니까요.

백엔드 팀도 좋아하는 이유

#

스펙이 단일 진실 공급원이 되면 일상적인 대화가 달라집니다. “이 엔드포인트가 뭘 반환하더라?“라는 채팅 스레드 대신, 프론트엔드는 생성된 타입을 읽으면 됩니다. 백엔드 개발자는 덜 끊기고, 피드백은 더 빨리 받습니다. 프론트엔드가 목을 상대로 만들어보다가 API가 어딘가 어색하다고 느끼면, 그걸 알게 되는 시점이 프로덕션 이후가 아니라 아직 고치기 싼 시점입니다.

우리 워크플로에 녹이는 방법

#

별다른 건 없습니다. 백엔드가 스펙을 제안하고, 양 팀이 리뷰하고, 프론트엔드는 Orval로 클라이언트와 목을 생성해 개발을 시작하고, 백엔드는 같은 계약에 맞춰 실제 엔드포인트를 구현합니다. 스펙이 바뀌면 양쪽에서 다시 생성하고, 뭐가 깨졌는지는 컴파일러가 정확히 알려줍니다. 사실 이 마지막 부분이 핵심입니다. 프론트와 백엔드 사이의 어긋남이 프로덕션 버그가 아니라 컴파일 에러가 되는 거죠.

설정하기

#

개발 의존성으로 설치하고, 생성된 코드가 import할 패키지도 함께 설치합니다. React Query 훅과 목을 쓸 거라면 TanStack Query, MSW, Faker입니다.

npm install --save-dev orval msw @faker-js/faker
npm install @tanstack/react-query

그다음 프로젝트 루트에 orval.config.ts를 추가합니다. 아래 설정은 Orval 공식 문서의 예제와 거의 같습니다.

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: './openapi.yaml', // a path or a URL
    },
    output: {
      mode: 'single',
      target: './src/api/petstore.ts',
      schemas: './src/api/model',
      client: 'react-query',
      httpClient: 'fetch',
      mock: true, // MSW handlers plus Faker data
      override: {
        fetch: { includeHttpResponseReturnType: false },
      },
    },
  },
});

무엇이 생성될지는 client가 정합니다. 그냥 fetch나 axios 함수, React Query·Vue Query·Svelte Query·SWR용 훅, Angular 서비스, Zod 스키마 중에서 고를 수 있습니다. includeHttpResponseReturnType: false 줄은 fetch 클라이언트가 { data, status } 대신 응답 바디 자체를 반환하게 하는데, 컴포넌트 입장에서는 대개 이쪽이 편합니다.

명령어를 아무도 외울 필요가 없도록 스크립트도 추가해 둡니다.

{
  "scripts": {
    "api": "orval"
  }
}

npm run api를 실행하면 훅과 모델이 생성됩니다. 컴포넌트에서는 여느 React Query 훅처럼 쓰면 되고, 타입은 이미 다 채워져 있습니다.

import { useListPets } from './api/petstore';

export function PetList() {
  const { data: pets, isLoading } = useListPets();
  if (isLoading) return <p>Loading…</p>;
  return (
    <ul>
      {pets?.map((pet) => <li key={pet.id}>{pet.name}</li>)}
    </ul>
  );
}

스펙에서 필드 이름을 바꾸고 npm run api를 다시 돌리면, pet.name을 쓰는 곳마다 빨간 줄이 그어집니다. 앞에서 말한 어긋남 검사가 바로 이것이고, 돌리는 데 드는 비용은 0입니다.

목을 상대로 개발하기

#

mock: true를 켜면 Orval은 엔드포인트마다 MSW 요청 핸들러도 만듭니다. 응답 스키마 모양 그대로의 Faker 데이터를 돌려주는 핸들러들이고, 이걸 전부 모아 반환하는 함수도 하나 생깁니다. 그 목록을 브라우저에서는 MSW의 setupWorker에, 테스트에서는 setupServer에 넘기면, 앱은 이미 계약과 일치하는 가짜 백엔드를 상대로 돌아갑니다. 핸들러마다 오버라이드도 받을 수 있어서, 특정 페이로드나 빈 목록, 에러 상태를 돌려주는 테스트를 누가 픽스처를 손으로 짜지 않아도 만들 수 있습니다.

프론트엔드가 첫날부터 작업을 시작할 수 있는 건 이 덕분입니다. 목은 누군가 따로 관리해야 하는 별도의 산출물이 아닙니다. 클라이언트와 같은 스펙에서 매번 다시 생성되니, 스펙보다 뒤처질 수가 없죠.

Orval과 openapi-generator, openapi-typescript, Hey API 비교

#

넷 다 OpenAPI 스펙에서 출발하지만, 멈추는 지점이 다릅니다.

타입만 필요하다면 openapi-typescript가 가장 가볍고, 딱히 반박할 거리도 없습니다. openapi-generator는 스펙 하나로 여러 언어를 먹여 살려야 할 때 제값을 합니다. TypeScript 출력도 동작은 하지만, 읽다 보면 Java를 먼저 염두에 두고 만든 티가 납니다. Orval과 Hey API 사이에서는 대체로 취향 문제이고, 어느 쪽이 내놓는 코드를 읽는 게 더 편한지로 갈립니다. 제가 계속 Orval을 쓰는 건 목이 훅과 같은 실행에서 함께 나오기 때문이고, 두 팀이 일하는 방식을 바꾼 게 바로 그 기능이었습니다.

화려한 도구는 아닙니다. 그저 팀 사이의 말다툼 한 종류를 통째로 조용히 없애줄 뿐인데, 저는 그 거래라면 언제든 응할 생각입니다.

기다림의 게임

#

전통적인 흐름은 직렬입니다. 백엔드가 API를 설계하고 구현한 뒤, 엔드포인트가 실제로 동작해야 프론트엔드가 통합을 시작합니다. 백엔드의 지연은 전부 프론트엔드 일정에 그대로 얹히는데, 릴리스 날짜가 적혀 있는 곳이 대개 프론트엔드 일정표입니다.

코드보다 계약이 먼저

#

스키마 우선 흐름에서는 양쪽이 거의 동시에 출발합니다. 코드가 한 줄도 없는 시점에 API 구조를 OpenAPI 스키마로 적어 둡니다. 모든 엔드포인트, 요청·응답 모델, 인증 방식, 에러 코드까지요. 이 문서가 프론트엔드와 백엔드 사이의 계약서가 됩니다.

효과는 바로 나타납니다. 만들기 전에 모두가 기능을 같은 모양으로 이해하게 됩니다. 백엔드가 구현 중인 동안 프론트엔드는 UI를 만들 수 있고요. 합의된 단일 진실 공급원 하나만 고치면 되니 변경도 빨리 돕니다. 게다가 스키마에서 바로 목 서버를 생성할 수 있어서, 진짜 엔드포인트가 하나도 없는 단계부터 프론트엔드 테스트가 시작됩니다.

실제로 돌리는 순서

#

1. 요구사항을 모읍니다. 뭘 만들든 똑같죠.
2. 스키마를 설계합니다. 엔드포인트, 요청/응답 모델, 인증, 에러 코드.
3. 프론트엔드와 백엔드 양쪽이 함께 리뷰합니다. 계약이 제값을 하는 순간이 바로 여기입니다.
4. 목 서버를 생성하고(Swagger, Postman 둘 다 됩니다) 프론트엔드는 그걸 상대로 통합을 진행합니다.
5. 백엔드는 같은 스키마에 맞춰 진짜 엔드포인트를 구현합니다.
6. 완성되는 대로 목을 진짜 엔드포인트로 갈아 끼우고, 계약이 지켜지는지 계속 테스트합니다.
7. 대화를 이어갑니다. 스키마는 살아 있는 문서지 석판이 아니니까요.

걸리는 부분

#

공짜는 아닙니다. 꼼꼼한 스키마를 미리 쓰는 데는 실제로 시간이 듭니다. 요구사항이 바뀌면 스키마부터 고쳐야 하고, 그 파장은 두 팀 모두에 미칩니다. 그리고 전원이 OpenAPI와 주변 도구에 최소한의 감은 갖고 있어야 하죠.

그래도 이 선행 투자가, 그 덕에 막을 수 있는 통합 지옥에 지는 걸 본 적이 없습니다. 프론트엔드는 첫날부터 달리기 시작하고, 논쟁은 깨진 빌드가 아니라 문서 위에서 벌어지게 됩니다.

광복절(8월 15일)은 1945년 일제강점기가 끝난 것을 기념하는 날이죠. Zdog은 <canvas>나 SVG에 3D 느낌의 일러스트를 그리는 작은 JavaScript 라이브러리입니다. 도형은 실제로 3D 공간 안에 놓이고 3D 물체처럼 돌아가지만, 그려지는 건 평면 도형이라 3D 렌더링이라기보다 돌려 볼 수 있는 평면 일러스트에 가깝습니다. 깃발처럼 단순한 걸 만들기에 딱 맞죠.

Zdog 최소 예제

#

도형 두 개, 드래그로 회전, 그리고 애니메이션 루프입니다.

<canvas class="zdog-canvas" width="240" height="240"></canvas>
<script src="https://unpkg.com/zdog@1/dist/zdog.dist.min.js"></script>
<script>
  const illo = new Zdog.Illustration({
    element: '.zdog-canvas',
    dragRotate: true, // drag to turn the scene
  });

  // a square, pushed back
  new Zdog.Rect({
    addTo: illo,
    width: 80,
    height: 80,
    translate: { z: -30 },
    stroke: 8,
    color: '#0047a0',
  });

  // a filled circle, pulled forward
  new Zdog.Ellipse({
    addTo: illo,
    diameter: 60,
    translate: { z: 30 },
    stroke: 8,
    color: '#cd2e3a',
    fill: true,
  });

  function animate() {
    illo.rotate.y += 0.02;
    illo.updateRenderGraph();
    requestAnimationFrame(animate);
  }
  animate();
</script>

도형은 addTo로 장면에 붙이고, 3D가 되는 건 translate.z 덕분입니다. 장면을 돌리면 원이 사각형 앞으로 돌아 나오죠. updateRenderGraph()가 전체를 갱신하고 다시 그리기 때문에 루프 안에 들어가 있습니다.

공식 문서

#

https://zzz.dog/

사용한 코드는 CodePen에서 볼 수 있습니다.

제가 만든 예제

#

제가 설정한 과정을 정리해 둡니다.

굳이 SASS를 쓰는 이유

#

순수 CSS는 페이지가 조금만 늘어나도 금세 지저분해집니다. SASS를 쓰면 변수, 중첩 규칙, 믹스인, 함수를 쓸 수 있어서 색상이나 공통 레이아웃 정의를 여기저기 복붙하지 않고 한곳에 모아둘 수 있습니다. Hugo 사용자에게 제일 반가운 점은, Hugo Pipes가 SCSS를 알아서 컴파일해 준다는 것. 별도의 빌드 도구도, 워처 스크립트도 필요 없습니다.

작업하는 동안 열어두면 좋은 페이지 두 곳:

• SASS 공식 문서
• Hugo의 SCSS/SASS 지원 문서

설정하기

#

1. assets 디렉토리 준비

#

Hugo는 프로젝트 루트의 assets 폴더를 찾기 때문에, 그 위치에 폴더를 만들거나 옮겨 주세요. resources 폴더 안에 두고 싶다면 config.toml에서 경로를 알려주면 됩니다.

assetDir = "resources/assets"

2. sass 폴더 만들기

#

assets 안에 sass라는 폴더를 만듭니다. SCSS 파일은 전부 여기에 둡니다.

3. 진입점 파일 추가

#

sass 폴더 안에 main.scss를 만듭니다. Hugo가 컴파일하는 파일이 바로 이것이니, 동작 확인 겸 SCSS 코드를 조금 넣어 봅시다.

// assets/sass/main.scss

// 변수
$primary-color: #3498db;

// 믹스인
@mixin center {
  display: flex;
  justify-content: center;
  align-items: center;
}

// 스타일
body {
  font-family: Arial, sans-serif;
  background-color: $primary-color;
}

h1 {
  @include center;
  color: white;
}

4. 템플릿에 연결

#

head.html 파셜에서 컴파일된 스타일시트를 불러와 압축합니다.

{{ $style := resources.Get "sass/main.scss" | resources.ToCSS | resources.Minify }}
<link rel="stylesheet" href="{{ $style.Permalink }}">

여기 적은 파일명이 실제 진입점(main.scss)과 일치하는지만 확인하면 됩니다.

스타일 파일 쪼개기

#

프로젝트가 커지면 SCSS를 파셜로 나누고 main.scss에서 임포트하세요.

// assets/sass/_variables.scss
$primary-color: #3498db;

// assets/sass/_mixins.scss
@mixin center {
  display: flex;
  justify-content: center;
  align-items: center;
}

// assets/sass/main.scss
@import "variables";
@import "mixins";

body {
  background-color: $primary-color;
}

h1 {
  @include center;
  color: white;
}

정말 이게 전부입니다. 네 단계면 끝나고, 빌드할 때마다 Hugo가 스타일을 다시 컴파일해 줍니다. 에셋 파이프라인과 한바탕 씨름할 각오였는데, 허무할 만큼 순순히 돌아가더군요.