이전 강의까지 FastAPI + Swagger (OpenAPI) + TypeScript 클라이언트 + **React(Vite)**를 연동해보았는데요. 시리즈 마지막인 5강에서는 실제 운영 환경에서 생길 수 있는 확장성과 배포 이슈, 그리고 대규모 팀/조직에서 적용할 때 유용한 고급 팁을 중심으로 살펴보겠습니다.
1. 대규모 프로젝트에서 고려해야 할 사항
1) 자동 생성된 코드 관리 전략
- 별도 Git 서브모듈 혹은 npm 패키지화
- 자동 생성된 코드를 메인 프로젝트와 분리해 버전 관리를 체계적으로 할 수 있습니다.
- 예: 회사 내부에서 API 클라이언트를 npm 패키지 형태로 배포하여, 여러 앱이 동일한 인터페이스를 사용하도록 유지.
- .gitignore 설정
- 빌드 결과물로 간주하여, 매 빌드 시마다 생성하고 배포하려는 경우에는 커밋 대상에서 제외할 수 있습니다.
- 하지만, 형상 관리가 필요한 경우에는 커밋 대상에 포함하는 편이 안전합니다.
주의사항: 가장 중요한 것은 API 스펙과 클라이언트 코드가 동기화되어야 한다는 점입니다. 배포 시점에 따라 불일치가 생기면 예상치 못한 오류가 발생할 수 있습니다.
2) CI/CD 파이프라인 연동
- 문서-코드 자동화 파이프라인
- 예: GitHub Actions, GitLab CI, Jenkins 등에 swagger-typescript-api 실행 단계를 삽입
- PR(Pull Request) 생성 시 자동으로 최신 클라이언트 코드를 다시 생성하고, 빌드·테스트가 통과하는지 체크
- 테스트 자동화
- 통합 테스트(Integration Test)에서 실제 서버(FastAPI)와 통신이 원활한지 검증하는 스크립트를 추가
- 예: Jest, Cypress, Playwright 등에서 API 호출 후 기대 결과가 맞는지 확인
"[캡쳐] CI/CD 파이프라인에서 swagger-typescript-api 실행 및 테스트 흐름"
이와 같은 다이어그램을 첨부하면 독자가 파이프라인 전반을 이해하기 쉽습니다.
2. 배포 시 주의사항 (프론트엔드 & 백엔드)
1) API 엔드포인트 관리
- Base URL이나 엔드포인트 주소가 환경(개발/스테이징/프로덕션)에 따라 달라질 경우, .env 파일 혹은 환경 변수를 사용해 동적으로 주입하도록 설계해야 합니다.
- 예:
# .env VITE_API_BASE_URL=https://api.prod.example.comconst apiClient = new TodoApi({ baseUrl: import.meta.env.VITE_API_BASE_URL, });
2) CORS 설정
- 운영 환경에서는 CORS 정책이 걸려 있는 경우가 많습니다.
- FastAPI 예시:
from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins=["*"], # 또는 특정 도메인만 allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) - 배포 후 브라우저에서 CORS 에러가 발생한다면, 백엔드 또는 프록시 레벨에서 CORS를 올바르게 설정했는지 확인하세요.
Tip: 보안상 production 환경에서는 allow_origins를 '*'로 전부 허용하지 않는 것이 권장됩니다. 특정 도메인만 허용하는 화이트리스트 방식을 고려하세요.
3. 모노레포 vs 멀티레포
1) 모노레포 (Monorepo)
- 장점: 백엔드(FastAPI), 프론트엔드(React), 그리고 자동 생성된 클라이언트 코드를 한 저장소에서 버전 동기화 가능.
- 단점: CI 파이프라인이 복잡해질 수 있고, 팀 규모가 커지면 충돌 관리가 어려울 수 있음.
2) 멀티레포 (Multi-Repo)
- 장점: 프로젝트 별로 책임을 명확히 분리. 독립적인 릴리스와 배포 파이프라인 설정 가능.
- 단점: API 스펙 변동 시, 여러 레포를 각각 업데이트해야 할 수 있음.
주의사항: 어느 방식이든 API 스펙 변경 → 클라이언트 재생성 → 프론트엔드 동기화 단계를 자동화할 수 있는 프로세스를 마련해야 합니다.
4. 확장성 있는 API 설계
1) 버저닝(Versioning)
- API 스펙에 버전을 도입하면, 기존 클라이언트를 사용하는 서비스가 깨지지 않도록 일정 기간 백워드 호환성을 유지할 수 있습니다.
- 예: /v1/todos, /v2/todos와 같이 경로로 버전을 구분하거나, HTTP 헤더를 이용하기도 합니다.
2) 스키마 분할 및 모듈화
- OpenAPI에서 components/schemas를 활용해 DTO(데이터 전송 객체)를 체계적으로 모듈화할 수 있습니다.
- 프로젝트가 커지면 각 도메인(예: User, Product, Order 등) 별로 분리해 관리하는 방식을 권장합니다.
5. 고급 Tip: 템플릿 커스터마이징
swagger-typescript-api는 기본적으로 Fetch API나 Axios 등을 활용해 코드를 생성하지만, 고급 커스터마이징이 필요한 경우 템플릿을 수정할 수 있습니다.
1) 템플릿 수정 예시
npx swagger-typescript-api \
--path "http://127.0.0.1:8000/openapi.json" \
--output "./generated" \
--name "MyCustomClient.ts" \
--templates "./custom-templates"
- --templates: .handlebars 형식의 템플릿 파일들을 두고, 원하는 로직(예: 에러 처리 방식, 로깅 등)을 재정의할 수 있습니다.
2) Custom Template 구조
- 보통 api.handlebars, models.handlebars, enum.handlebars 등이 제공되며, 여기서 생성될 함수와 클래스의 구조를 세세하게 조정 가능합니다.
주의사항: 템플릿 커스터마이징은 유지보수 비용이 늘어날 수 있으므로, 단순히 옵션 조정만으로 해결 가능한 문제인지 먼저 확인하는 것을 추천합니다.
6. 마무리
이번 5강에서는 프로젝트 확장과 배포 전략을 중심으로, 대규모 팀/조직에서 swagger-typescript-api를 어떻게 적용하고 운영할 수 있을지를 다뤘습니다.
- 자동화 파이프라인: OpenAPI 스펙과 클라이언트 코드의 동기화를 CI/CD에 통합
- API 버저닝 & 스키마 모듈화: 대규모 확장성을 대비한 설계
- 템플릿 커스터마이징: 보다 정교한 코드 생성이 필요한 경우
이제 이 시리즈의 여정이 끝났습니다. 전체를 관통하는 핵심은 **“OpenAPI 스펙 기반의 타입 안전한 코드 자동화”**를 통해 생산성과 유지보수성을 극대화한다는 점입니다. 이 과정을 통해 여러분의 프로젝트와 팀 협업이 한층 더 발전되길 바랍니다.
감사합니다! 🚀