▲

Show GN: Spine - 한국에서 만든, 마법 없는 백엔드 웹 프레임워크

 (na2ru2.me)
7P by narubrown 12시간전 | ★ favorite | 댓글과 토론
  • Spine은 실행 흐름을 숨기지 않고 명시적으로 드러내는 Go 기반 백엔드 웹 프레임워크
  • 단일 Pipeline이 전체 실행 순서를 소유하며, Controller는 비즈니스 로직에만 집중
  • 메서드 시그니처가 곧 API 계약이며, 어노테이션이나 컨벤션 기반 자동화 없음
  • 요청 순서가 코드에서 명확히 보임
  • 초기 생산성보다 장기 유지보수성과 실행 흐름 추적 용이성에 초점
  • Echo를 HTTP Transport로 사용하며, ORM 비종속 설계로 Bun/GORM등 자유롭게 선택 가능

Spine 개요

Spine은 웹 요청의 실행 흐름을 명시적으로 드러내는 것을 목표로 한 프레임워크
대부분의 프레임워크가 편의를 위해 숨기는 실행 순서를 코드 구조로 고정
"요청이 어디서 시작되어, 누가 처리하고, 어떤 순서로 실행되는가"에 명확히 답할 수 있는 구조 지향

설계 원칙

마법 없음 정책

  • 실행 순서를 아는 컴포넌트는 Pipeline 하나뿐
  • "알아서 해주는" 동작을 최소화
  • 모든 확장과 실행은 명시적으로 등록되고 예측 가능한 순서를 가짐

시그니처 기반 계약

  • 메서드 기그니처가 곧 API 계약
  • 입력 생성은 ArgumentResolver, 출력 처리는 ReturnValueHandler가 담당
  • 어노테이션 기반 매핑, 컨벤션 기반 자동 추론 금지

Controller 독립성

  • Controller는 HTTP/Transport 타입에 의존하지 않음
  • path., query., httperr.* 같은 의미 타입만 사용
  • 실행 모델을 모르되, 입력의 출처는 타입으로 명시

주요 기능

라우팅 및 파라미터

  • Path Parameter 지원 (순서 기반 바인딩)
  • Query Values 유틸리티 (Int, String, Boolean 파싱)
  • Body DTO 자동 바인딩

응답 처리

  • ReturnValueHandler로 struct -> JSON 자동 변환
  • error -> HTTP 상태 코드 자동 매핑
  • httperr.NotFound, BadRequest 등 의미 기반 에러 타입

횡단 관심사

  • Interceptor (PreHandle, PostHandle, AfterCompletion)
  • CORS Interceptor 내장
  • 생성자 기반 IoC Container

아키텍처

  • Transport 계층 분리 (현재 Echo, 교체 가능하도록 설계됨)
  • ORM 비종속 설계 (Bun, GORM 등 자유롭게 사용가능 ⚠️현재 Bun만 호환성 확인됨)

대규모 환경에서의 강점

실행 순서를 아는 주체가 하나뿐이므로 요청 흐름 추적 비용이 감소
로깅, 트랜잭션, 보안 같은 횡단 관심사는 Pipeline에만 배치되어 적용 지점과 타이밍이 예측 가능 초기 생산성을 일부 포기하고 장기적으로 증가하는 복잡성을 구조로 흡수하는 전략

Spine이 아닌 것

  • Spring/NestJS의 대체제가 아님
  • 생산성 극대화 프레임워크가 아님
  • 어노테이션 기반 자동화 프레임워크가 아님
  • HTTP Engine 이나 Router 중심 프레임워크가 아님

Spine은 도움이 필요한 프로젝트

Spine은 아직 완성된 프레임워크가 아님 의도적으로 많은 부분을 미완성 상태에서 공개
구조가 충분히 설명 가능한지, 실행 모델이 실제 문젤르 잘 드러내는지 검증 필요

참여 방법

  • GitHub에서 ⭐️를 눌러 프로젝트를 지켜봐 주기
  • 사용해보며 느낀 점이나 의문을 이슈로 남겨주기
  • 설계에 대한 비판, 제안, 질문을 댓글로 남겨주기

참고 링크