기존 API에 영향을 주지 않고 새 기능을 개발하는 방법 – FastAPI 구조 기준

FastAPI로 백엔드를 개발하면서 흔히 겪는 고민이 하나 있습니다.

“기존에 잘 돌아가던 admin API를 건드리지 않으면서, 새롭게 user/service 관련 API를 개발하고 싶은데… 스키마나 DB 구조까지 바꿔야 할 것 같을 땐 어떻게 하지?”

이런 상황에서 직접 겪은 삽질과 복구 경험을 토대로, 실전에서 유용했던 API 개발 격리 전략을 공유합니다.

---

문제 상황 ** 내 프로젝트는 다음과 같은 구조를 갖고 있다:

app/
├── api/v1/endpoints/admin/      ← 운영 중인 안정된 관리자 API
├── api/v1/endpoints/users/      ← 새로 개발해야 할 사용자 API
├── api/v1/schemas/*.py
├── models/
├── crud/

새로 만드는 user/game API는 스키마, DB, 모델, CRUD 구조까지 영향을 줄 수 있는 작업이고, 이 과정에서 기존 admin API가 고장날 우려가 있었다. 실제로 그런 일이 발생해서 git으로 복구한 적도 있었다 😵‍💫

---

• 새 기능은 api/v2/ 아래에서 완전히 분리된 구조로 개발
• 기존 admin 기능은 v1 그대로 유지

app/
├── api/
│   ├── v1/                     ← 기존 유지
│   └── v2/                     ← 새 기능 개발
│       ├── endpoints/users/
│       └── schemas/
├── models/
│   ├── user.py
│   └── v2/user.py              ← 모델 구조가 다를 경우 분리
├── crud/
│   ├── user.py
│   └── v2/user.py

2. API 라우터 분리 ** api/api.py에서 v1과 v2를 명확히 나눔:

api_router.include_router(admin_router, prefix="/v1/admin", tags=["admin"])
api_router.include_router(v1_user_router, prefix="/v1/users", tags=["v1-users"])
api_router.include_router(v2_user_router, prefix="/v2/users", tags=["v2-users"])

• Alembic 마이그레이션은 가급적 브랜치 분기 후 staging DB에서 테스트
• 운영용 DB와는 철저히 분리한 개발 환경을 마련 (Docker, .env.dev 활용)

tests/
├── test_admin_utils.py          ← 기존 유지
└── v2/
    └── test_users.py            ← 신규 테스트

---

핵심 요약

구분	기존 admin 유지	새로운 user/game 개발
라우팅	/v1/admin/…	/v2/users/… 등
폴더 구조	api/v1/	api/v2/
모델	models/user.py	models/v2/user.py
테스트	tests/	tests/v2/
마이그레이션	운영 DB	개발용 DB 또는 브랜치별 진행

---