Cloudflare로 구현하는 유연한 라우팅

요약: api.huny.dev 같은 도메인에서 경로(prefix)별로 동적 라우팅해 /v1은 API로, /docs는 Mintlify 정적 문서로 보내는 구조를 Cloudflare Workers로 쉽게 만들 수 있다. TLS/인증서엔 영향 없다(도메인 단일, 라우팅은 L7에서 처리).

왜 이렇게 쓰나

• 버전형 API: /v1, /v2로 나눠 점진적 마이그레이션.

• 문서/콘솔 공존: /docs는 Mintlify, /console은 내부 대시보드, /healthz는 헬스체크 등.

• 미래 대비: 처음부터 경로 규칙만 추가하면 신규 서비스 붙이기 쉬움(서브도메인 추가 없이).

아키텍처 개요

• 인증서: api.huny.dev 하나로 커버. Worker는 L7 프록시이므로 인증서 검증 흐름에 문제 없음.

• 정적 레이어(Mintlify) 앞단에서 prefix 파싱만 하고, 나머지는 원본에 투명 프록시.

Worker 예시 코드 (TypeScript / Module syntax)

Cloudflare 라우팅 & 환경변수

• Route: api.huny.dev/* → 위 Worker 바인딩.

• Vars (Pages/Workers → Settings → Variables):
• V1_API_HOST = v1.huny-api.internal
• V2_API_HOST = v2.huny-api.internal
• MINTLIFY_HOST = huny-docs.netlify.app (또는 docs.huny.dev CNAME)
• STATIC_HOST = cdn.huny.dev
• SVC_TOKEN = (선택)

Mintlify 측 설정 팁

• Mintlify를 Netlify/Vercel에 올린 뒤 도메인 별도(예: docs.huny.dev)로도 접근 가능하게 해두면, Worker 프록시/직접접속 둘 다 유연하게 사용 가능.

• 내부 경로가 / 기준이라면 Worker에서 /docs → /로 rewrite 처리(위 예시처럼).

캐싱·성능 최적화

• /docs·/assets는 Cache-Control 헤더를 원본에서 세팅하고, Worker에서 그대로 전달(패스스루).

• /v1/* /v2/*는 일반적으로 no-store 또는 짧은 TTL.

• Cloudflare Cache Reserve / Tiered Cache는 정적 자산에만 적용.

롤아웃 전략

• /v1 유지 + /v2 점진 추가 → 기능별로 라우팅 스위치.

• 트래픽 일부만 /v2로 보내는 샘플링:

관측/모니터링

• Worker에서 요청 메타(경로, 응답코드, 백엔드 지연) 로그를 Logpush/Analytics Engine으로 적재.

• /healthz는 각 백엔드별 별도 엔드포인트도 만들어 두고 주기 체크.

실패 시 폴백

• 특정 백엔드 장애 감지 시 /v2/* → /v1/*로 임시 리라이트 하는 스위치:

보안 포인트

• 엣지에서 JWT 검증 또는 HMAC 시그니처 선검증 가능(백엔드 부담 감소).

• 내부 원본은 **Zero Trust(Access/MTLS/IP 제한)**로 보호, 공용 노출 최소화.