API Development and E2E Test Flow

Pipeline Overview

로컬 개발
   ↓
단위 및 계약 테스트
   ↓
자동 배포
   ↓
게이트웨이 동기화
   ↓
End-to-End 검증
   ↓
런타임 모니터링

각 단계는 이전 단계보다 더 엄격한 검증을 제공합니다.

Design Principles

1. Contract as Source of Truth — API 동작은 스키마·OpenAPI로 정의.
2. Gateway-Aware Validation — API는 최종 사용자와 동일한 게이트웨이로 테스트.
3. Progressive Risk Reduction — 결함은 가능한 한 이른 단계, 낮은 비용으로 제거.
4. Deployment as Test Boundary — E2E 검증 없이 배포 성공 = 정확성 보장 아님.
5. Observability as Continuation of Testing — 런타임 모니터링은 사전 테스트를 보완.

Stage 1 – API 개발 및 단위 검증

• API는 스키마 검증 기반 핸들러로 구현.
• 단위 테스트는 D1, KV 등 시뮬레이션/모킹 환경에서 수행.
• 통과 기준: 모든 단위 테스트 통과, 스키마 위반 시 다음 단계 진행 불가.

Stage 2 – 배포 및 계약 공개

• main 병합 코드는 배포 가능해야 하며, CI/CD로 자동 배포.
• API 계약은 OpenAPI 형식으로 출력, 게이트웨이와 자동 동기화.

Stage 3 – E2E 검증

• 실행 시점: 배포 성공 이후 반드시 실행.
• 대상: 내부 서비스가 아니라 게이트웨이 엔드포인트.
• 범위: 인증 성공/실패, 핵심 비즈니스 플로우, 계약 준수(상태 코드, 응답 구조).
• 실패 시: 배포 실패로 간주, 릴리스/프로덕션 승격 차단.

Stage 4 – 런타임 모니터링

• 런타임 오류 실시간 수집 (스택 트레이스, 요청 메타데이터, Correlation ID).
• 치명적 오류 즉시 알림.
• 모니터링 데이터로 단위 테스트·E2E 시나리오·계약 정제에 피드백.

Environment Segmentation (권장)

환경	목적
Development	로컬 반복 개발
Staging	배포 + E2E 검증
Production	실제 사용자 트래픽

E2E는 프로덕션 승격 전 스테이징에서 실행.

Conformance Levels (선택)

• Level 1: 단위 테스트 + 배포
• Level 2: 게이트웨이 동기화 + E2E
• Level 3: E2E + 런타임 관측 (완전 적합)