dpdpdndn 블로그

FE-03-bff-route-handlers

NEW2 min read

[FE-03] 피처 플래그 BFF Route Handler (BE 프록시 7종)

작업 내용 (설계 의도)

변경 사항

브라우저 → 동일 출처 BFF → BE 프록시 계층을 구현한다. 레포 관례(app/api/admin/mcp/tokens/route.ts + forwardBeResponse + zodValidationError)를 그대로 따른다. 컴포넌트가 BE를 직접 호출하지 않게 하는 필수 계층(no-direct-fetch). 근거 설계: ../design-fe-web.md “API 연동 표”.

  • web/app/api/admin/feature-flags/route.ts: GET(?status=&type= → BE로 전달), POST(body를 CreateFeatureFlagInputSchema.parse 후 forward, ZodError→zodValidationError).
  • web/app/api/admin/feature-flags/[key]/route.ts: GET(상세), PUT(UpdateFeatureFlagInputSchema.parse 후 forward).
  • web/app/api/admin/feature-flags/[key]/archive/route.ts: POST.
  • web/app/api/admin/feature-flags/[key]/activate/route.ts: POST.
  • web/app/api/admin/feature-flags/[key]/audit-logs/route.ts: GET(?page=&size=).
  • 모든 핸들러는 forwardBeResponse("/admin/feature-flags...", {...})로 BE 경로에 프록시. BE 4xx(400/404/409)·5xx·503은 헬퍼가 사용자 메시지로 매핑. JWT는 be-client가 쿠키에서 자동 첨부.

롤백

신규 라우트 파일 삭제로 롤백. 기존 BFF 무영향.

의존

  • FE-01 (입력 스키마 parse)

다이어그램

처리 흐름

sequenceDiagram
    participant C as Client 훅
    participant B as BFF Route Handler
    participant BE as Backend
    C->>B: POST /api/admin/feature-flags {body}
    B->>B: CreateFeatureFlagInputSchema.parse(body)
    B->>BE: forwardBeResponse POST /admin/feature-flags
    BE-->>B: 201 or 400/409
    B-->>C: forward (사용자 메시지 매핑)

테스트 케이스

  • POST에 유효 body 전달 시 BE로 프록시되고 BE 201 응답이 그대로 forward된다 (be-client mock)
  • POST에 percentage>100 body 전달 시 zod 검증 400을 반환하고 BE를 호출하지 않는다
  • 깨진 JSON body 전달 시 400을 반환한다
  • GET ?status=ARCHIVED 전달 시 쿼리스트링이 BE 경로에 붙어 프록시된다
  • BE가 404를 반환하면 404 + 사용자 메시지가 forward된다
  • BACKEND_URL 미설정 시 503을 반환한다

그래프 뷰