ADR-0003: HTTP Framework: Echo¶
Umbra 의 HTTP API 프레임워크로 Echo v4 를 채택한다.
Status¶
Accepted
- Decided at — 2026-04-13
- Decided by — Pablo
Context¶
Umbra 의 API 프로세스는 세 가지 책임을 가진다.
- 사용자 대시보드 API (
app.umbra.ink) - 웹 조인 플로우 (
join.umbra.ink/{slug}) - Toss 웹훅 수신 (
/webhooks/toss)
결제 SaaS 이므로 보안 기본값(CSRF, Rate Limit, Security Headers), 인증(Discord OAuth2 + 세션), 검증(request binding + validation), Rate Limit 이 견고해야 한다.
Go HTTP 프레임워크 후보: net/http + chi, Echo, Gin, Fiber.
특히 페어 개발 맥락에서 "보안 미들웨어 표준화" 가 중요하다. 진욱이 보안 헤더, CSRF 방어를 직접 구현할 부담을 줄이고 프레임워크가 제공하는 검증된 패턴을 쓰는 것이 안전하다.
Decision¶
Echo v4 를 HTTP API 프레임워크로 채택한다.
선택 근거:
- 보안 미들웨어 내장 — CSRF, CORS, Secure Headers, Rate Limit, Session, JWT, Body Limit 이 공식 미들웨어로 제공
- Validation 통합 —
echo.Validator인터페이스로go-playground/validator통합 - Binding — Query, Param, Body, Header 자동 바인딩으로 보일러플레이트 감소
- OpenTelemetry 공식 통합 —
otelecho미들웨어 제공 - 한국 개발자 친숙도 — Go 프레임워크 중 국내 사용 빈도 높음
- 문서화 품질 — 공식 가이드가 체계적이며 예제 풍부
Consequences¶
Positive¶
- 보안 기본값을 빠르게 확보 (CSRF, HSTS, CSP, Rate Limit 모두 한 줄씩)
- 사용자 대시보드 폼 처리 시 binding + validation 으로 코드 감소
- OpenTelemetry 통합으로 관측성 구현 부담 ↓
- 진욱의 부담 감소 (미들웨어 직접 구현 대신 설정)
Negative¶
- 자체
echo.Context가 표준http.Handler와 다름 → 일부 라이브러리 어댑터 필요 - 런타임 디스패치 기반으로 net/http 직결보다 미세한 오버헤드
- 도메인 코어에서 echo 타입이 새어나가지 않도록 Anti-Corruption Layer 유지 필요
Neutral¶
- Echo 버전 업그레이드 시 미들웨어 호환성 확인 필요
- 핸들러는
apps/api/internal/handler/에서만 Echo 를 직접 사용
Alternatives considered¶
Alternative 1: net/http + chi¶
Pros
- Go 표준
http.Handler호환 100% - 가장 얇은 라우터 (학습 부담 최소)
- 모든 미들웨어/라이브러리와 즉시 통합
Cons
- CSRF, Session, OAuth2, Security Headers 를 별도 라이브러리로 조합해야 함 (gorilla/csrf, alexedwards/scs, markbates/goth, unrolled/secure)
- 다섯 개 라이브러리 조합의 일관성 유지 비용
- 보안 미들웨어 직접 구현 시 누락 위험
Why rejected — 프레임워크가 깔아주는 보안 기본값의 가치가 조립식 자유도 대비 큼. 결제 SaaS 에서 누락 위험을 최소화하는 것이 우선.
Alternative 2: Gin¶
Pros
- Go 진영 가장 인기
- 성능 벤치마크 우수
- 미들웨어 커뮤니티 활발
Cons
- CSRF 공식 미들웨어 부재 (서드파티 의존)
- 에러 처리 패턴이 Go 표준과 거리 있음
- 컨벤션이 강제적이라 자유도 낮음
Why rejected — CSRF 공식 지원 부재가 결제 SaaS 에 치명적. 서드파티로 해결 가능하지만 Echo 가 같은 기능을 공식으로 제공.
Alternative 3: Fiber¶
Pros
- fasthttp 기반으로 가장 빠름
- Express.js 스타일로 Node 배경 개발자에 친숙
Cons
- 표준
net/http미호환 (fasthttp) → OpenTelemetry, Prometheus, 대부분의 Go 라이브러리와 호환성 문제 - Graceful shutdown 처리가 표준과 다름
Why rejected — 표준 비호환이 결정적. OpenTelemetry 통합 복잡도와 라이브러리 제약이 성능 이점을 상쇄.
Alternative 4: Hono (BFF 로)¶
이 대안은 ADR 스펙상 아키텍처 수준 결정이라 architecture/overview.md 에서 다룬다. 요약: Hono BFF 를 Echo 앞에 두는 구조를 검토했으나 MVP 에 과도한 복잡도로 거부. Echo 단일 백엔드로 진행.
Compliance¶
- API 프로세스(
apps/api/)에서만 Echo 직접 import - 도메인 코어에서 echo 타입 import 금지 (golangci-lint 로 강제)
- 모든 핸들러는 Echo 의 Validator 를 사용 (validator v10)
- Security Headers, CSRF, Rate Limit, Session 미들웨어는 기본 적용
Revisit triggers¶
- Echo 의 메이저 버전 변경 시 마이그레이션 ADR 별도 작성
- BFF 계층이 진짜 필요해지면 Hono/Elysia 같은 별도 레이어 검토
- 외부 API (개발자 서비스로 공개) 확장 시 OpenAPI-first 프레임워크 (huma 등) 재평가