🧬 NestJS API Versioning – 안정적인 서비스 확장을 위한 버저닝 전략

🧬 NestJS API Versioning – 안정적인 서비스 확장을 위한 버저닝 전략

---

NestJS는 API 버전 관리(versioning) 기능을 공식적으로 지원하여,
서비스 중단 없이 새로운 API 버전을 도입하거나, 구버전과의 호환을 유지할 수 있도록 돕습니다.
이번 글은 NestJS 공식 문서 Versioning을 바탕으로
URL, 헤더, 미디어 타입, 커스텀 전략을 통한 API 버저닝 전략을 실무 중심으로 정리했습니다.

💡 “버전관리는 성장하는 서비스에서 필수입니다. V1 → V2로 API를 진화시키면서도 구 사용자에게 혼란을 주지 마세요!”

---

✅ 1. 전역 버전 전략 활성화

// main.ts
import { VersioningType } from '@nestjs/common';

const app = await NestFactory.create(AppModule);

app.enableVersioning({
  type: VersioningType.URI, // or HEADER, MEDIA_TYPE, CUSTOM
});

---

🔢 2. URI 방식 – 가장 명확하고 널리 사용됨

 

@Controller({ path: 'cats', version: '1' })
export class CatsControllerV1 {
  @Get()
  findAll() {
    return 'This is version 1';
  }
}

@Controller({ path: 'cats', version: '2' })
export class CatsControllerV2 {
  @Get()
  findAll() {
    return 'This is version 2';
  }
}

요청 예시

GET /v1/cats
GET /v2/cats

☑️ RESTful한 서비스에서는 가장 직관적이고 문서화도 쉬움

---

🧠 3. Header 방식 – 클라이언트에 노출되지 않도록

app.enableVersioning({
  type: VersioningType.HEADER,
  header: 'x-api-version',
});

@Controller({ path: 'cats', version: '1' })

요청 예시

GET /cats
Headers: { x-api-version: 1 }

☑️ 웹 앱, 모바일 앱에서 헤더로 전송하는 경우 유리함
❗ API 테스트/문서화는 복잡해질 수 있음

---

<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-XXXXXX"
     data-ad-slot="YYYYYY"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>

---

🧪 4. Media Type 방식 (Accept 헤더 사용)

app.enableVersioning({
  type: VersioningType.MEDIA_TYPE,
});

@Controller({ path: 'cats', version: '1' })

요청 예시

GET /cats
Headers: Accept: application/vnd.api+json;version=1

☑️ GraphQL, REST HAL, JSON API 등에서 사용
❗ 구현 난이도와 테스트 복잡도는 상대적으로 높음

---

🧩 5. Custom 전략도 지원됨

app.enableVersioning({
  type: VersioningType.CUSTOM,
  extractor: (request: Request) => {
    return request.headers['custom-version'] as string;
  },
});

☑️ 요청의 cookies, query, headers, params 등 어디서든 버전 추출 가능

---

✅ 6. 메서드 레벨에서 버전 설정도 가능

@Controller('cats')
export class CatsController {
  @Get()
  @Version('1')
  getV1() {
    return 'v1';
  }

  @Get()
  @Version('2')
  getV2() {
    return 'v2';
  }
}

☑️ 하나의 컨트롤러 내에서 다중 버전을 공존시킬 수 있는 방식

---

🧠 실무 전략 요약

버전 전략 설명 장점 단점

URI	/v1/cats, /v2/cats	직관적, 문서화 쉬움	경로 변경으로 라우팅 증가
HEADER	x-api-version	URL 일관성 유지	테스트/문서화 번거로움
MEDIA_TYPE	Accept: ...;version=1	포맷 기반 API에 유리	난이도 높음
CUSTOM	쿠키, 쿼리 등 커스텀	유연성 최고	유지보수 복잡

---

📌 실무 팁

• 버전 증가 시 명확한 마이그레이션 문서 제공 필수
• Swagger 연동 시 version별 그룹화를 통해 문서화 권장
• VersioningType.URI + @Version() 조합은 확장성과 관리에 매우 유리

---

 

NestJS API Versioning,NestJS 버전 관리,NestJS REST API 버전,NestJS Header 기반 버전,NestJS Custom Version,NestJS Media Type 버전,NestJS URI 버저닝,NestJS Versioning 전략,NestJS Swagger 버전 문서화,NestJS 실무 API 구조

---