마이크로서비스 환경에서 Base URL 효과적으로 관리하기

Base URL이란?

Base URL은 API 엔드포인트의 반복되는 주소 부분입니다:

전체 URL: https://api.example.com/v1/users
Base URL: https://api.example.com/v1
경로:     /users

기본 설정

Environment Management에서 설정

1. 우측 상단의 Environment Management 접근
2. 기본 환경 (development, testing, production) 확인
3. 프로토콜(http:// 또는 https://) 포함하여 주소 입력

중요: OpenAPI 스펙에 따라 후행 슬래시를 포함하지 않습니다.

✅ https://api.example.com/v1
❌ https://api.example.com/v1/

엔드포인트에서 사용

엔드포인트 생성 시 경로만 입력하면 Base URL이 자동으로 결합됩니다:

Base URL: https://api.example.com/v1
경로 입력: /users
최종 URL: https://api.example.com/v1/users

다중 환경 관리

대부분의 프로젝트는 여러 환경을 사용합니다:

환경 전환

우측 상단에서 환경을 전환하면 모든 엔드포인트의 Base URL이 자동으로 변경됩니다.

Development 선택 → 모든 요청이 localhost로
Production 선택 → 모든 요청이 프로덕션 서버로

마이크로서비스 아키텍처

마이크로서비스에서는 각 서비스가 다른 주소를 가집니다:

방법 1: 수동 설정 (기본)

특정 폴더나 개별 엔드포인트에 다른 Base URL을 할당합니다.

📁 User Service
   └─ Base URL: https://user.example.com
   └─ GET /profile
   └─ POST /register

📁 Product Service
   └─ Base URL: https://product.example.com
   └─ GET /list
   └─ GET /{id}

📁 Order Service
   └─ Base URL: https://order.example.com
   └─ POST /create
   └─ GET /history

단점: 서비스가 늘어날수록 관리가 복잡해집니다.

방법 2: 모듈 기반 설정 (권장)

각 서비스를 별도 모듈로 만들고, Environment Management에서 모듈별 Base URL을 설정합니다.

프로젝트
├─ Module: User Service
├─ Module: Product Service
└─ Module: Order Service

Environment Management:
┌─────────────┬─────────────────────────┬─────────────────────────┬─────────────────────────┐
│ Environment │ User Service            │ Product Service         │ Order Service           │
├─────────────┼─────────────────────────┼─────────────────────────┼─────────────────────────┤
│ Production  │ https://user.example.com│ https://product.example.com│ https://order.example.com│
│ Testing     │ http://192.168.1.10:8080│ http://192.168.1.11:8080│ http://192.168.1.12:8080│
│ Development │ http://localhost:3000   │ http://localhost:3001   │ http://localhost:3002   │
└─────────────┴─────────────────────────┴─────────────────────────┴─────────────────────────┘

모듈 + 환경 좌표 시스템

이 방식의 핵심은 모듈 + 환경 조합으로 Base URL이 자동 결정된다는 것입니다:

요청 실행 시:
├─ 현재 모듈: Product Service
├─ 현재 환경: Testing
└─ 자동 적용 Base URL: http://192.168.1.11:8080

실무 팁

1. API 버전을 Base URL에 포함

✅ https://api.example.com/v2
   → 버전 변경 시 Base URL만 수정

❌ https://api.example.com
   → 모든 엔드포인트에 /v2 추가 필요

2. 개별 엔드포인트 오버라이드

특정 엔드포인트에 전체 URL을 입력하면 Base URL 설정을 무시합니다:

Base URL: https://api.example.com
엔드포인트: https://different-api.com/special  ← 이 URL이 그대로 사용됨

3. 환경 변수 활용

Base URL: {{BASE_URL}}

환경별 설정:
- Development: BASE_URL = http://localhost:3000
- Production: BASE_URL = https://api.example.com

4. 게이트웨이 패턴

마이크로서비스를 API 게이트웨이 뒤에 배치:

Base URL: https://gateway.example.com/api

경로:
- /users/* → User Service
- /products/* → Product Service
- /orders/* → Order Service

트러블슈팅

CORS 오류

Access-Control-Allow-Origin 헤더 확인
→ 개발 환경에서 프록시 설정 고려

SSL 인증서 오류

개발 환경: http:// 사용
프로덕션: https:// 필수
자체 서명 인증서: 검증 비활성화 옵션

포트 충돌

로컬에서 여러 서비스 실행 시:
- User: localhost:3000
- Product: localhost:3001
- Order: localhost:3002

결론

Base URL 관리는 단순해 보이지만, 프로젝트 규모가 커지면 체계적인 관리가 필수입니다. 특히 마이크로서비스 환경에서는 모듈 기반 설정을 통해 환경과 서비스의 조합을 깔끔하게 관리하세요.