분산 컴포넌트를 견고한 시스템으로 만드는 Service Layer 설계 전략

Context

개별적으로 작동하는 스키마와 Embedding 레이어의 단순 결합 구조. 컴포넌트 간 경계에서 발생하는 예외 처리 및 상태 관리 부재. 데이터베이스 변경이 API 계약에 직접 영향을 주는 강한 결합 문제.

Technical Solution

• Controller와 구현체 사이에 Interface를 도입하여 외부 의존성을 격리하고 테스트 가능성 확보
• Entity 객체의 경계 외부 유출을 차단하고 DTO만을 주고받는 구조로 API 계약과 DB 스키마의 독립적 진화 보장
• 'Save-First, Embed-Second' 전략을 통해 PENDING 상태로 우선 저장 후 Embedding을 수행하여 프로세스 충돌 시 복구 지점 마련
• Embedding 실패 시 상태를 FAILED로 명시하고 에러 로그를 DB에 기록하여 디버깅 가능한 데이터 흐름 구축
• (status, created_at DESC) 복합 인덱스를 활용해 READY 상태의 문서만 빠르게 필터링하는 검색 최적화 설계
• QueryBuilder를 통한 동적 SQL 생성 및 Cosine Distance 기반의 랭킹 시스템 구현

Key Takeaway

서비스 레이어는 단순한 로직 전달자가 아니라 시스템의 예측 가능성을 결정하는 비즈니스 규칙의 소유자이며, 실패를 데이터로 전환하는 설계가 시스템의 가시성을 결정함.