Read Original
#Backend

헥사고날 아키텍처, Adapter만 바꾸면 될까

헥사고날 아키텍처, Adapter만 바꾸면 될까
01

Summary

"정말 어댑터만 바꾸면 끝일까?" 헥사고날 아키텍처의 이상과 현실

AWS S3에서 국내 클라우드로 파일 저장소를 마이그레이션하며 검증한 헥사고날 아키텍처의 진짜 비용

본 아티클은 HR SaaS 플랫폼 플렉스(flex)가 데이터 국내 보관 요건 충족을 위해 클라우드 스토리지 이전 작업을 수행하며 겪은 실전 아키텍처 검증기입니다. 소프트웨어 설계 이론으로만 접하던 헥사고날 아키텍처의 '어댑터 교체성'이 완벽히 작동하기 위해 필요한 실질적인 개발 전제 조건들과, 그럼에도 불구하고 코드가 구원해 주지 못하는 실제 인프라 영역의 현실적인 난관들을 가감 없이 풀어냅니다.

  • 01AWS SDK 패키지 임포트를 오직 최상위 조립 모듈에만 허용하여 도메인 핵심 로직으로의 기술 유출을 완벽히 차단했습니다.
  • 02Port 계약 설계 시 Bucket, S3 등 특정 벤더의 흔적을 철저히 배제하고 도메인 모델만 주고받도록 엄격하게 격리했습니다.
  • 03메타데이터 처리 방식, 유효기간 상한 규격 차이 등 CSP별 기술적 미세 차이를 Adapter 내부 로직으로 깔끔하게 캡슐화했습니다.
  • 04클라우드 백엔드가 달라지더라도 동일한 애플리케이션 빌드 산출물을 그대로 사용할 수 있음을 실증했습니다.
  • 05네트워크 VPC 재설계, 배포 파이프라인 수정, 실제 데이터 마이그레이션 등 코드 외적인 공수가 전체 프로젝트 리소스의 상당 부분을 차지함을 명시했습니다.

RECOMMENDATION

멀티 클라우드 유연성을 확보하려는 백엔드 아키텍트들에게 추천하며, 추후 인프라 전환이 발생했을 때 진짜 '어댑터 추가'만으로 대응하고 싶다면 초기 단계부터 SDK 의존성을 빌드 가드레일 단위에서 차단하는 방어적 격리 환경 구축을 권장합니다.

The Problem

개인정보보호법 및 고객사 계약상의 국내 데이터 보관 요건을 만족하기 위해, 기존 AWS S3 기반의 파일 저장소를 국내 CSP의 오브젝트 스토리지로 이전해야 하는 배경이 발생했습니다.

The Solution

헥사고날 아키텍처를 기반으로 도메인 모듈에서 AWS SDK 의존성을 완전히 제거하고, 특정 벤더에 종속되지 않은 추상화된 Port 계약을 정의한 뒤 신규 CSP를 지원하는 Adapter를 추가로 구현하여 전환했습니다.

The Result

애플리케이션 영역에서는 코드 수정 없이 설정 프로퍼티 한 줄만 변경하여 저장 백엔드를 성공적으로 전환하고 빌드 산출물의 단일성을 유지했으나, 전체 이전 작업 일정의 대부분은 코드 바깥의 인프라 정의 및 데이터 마이그레이션에 소요되었습니다.

Trade-off

헥사고날 아키텍처가 애플리케이션 코드 수준의 영향도는 완전히 격리해 주지만, 인프라 정의(IaC) 재작성, 배포 파이프라인 수정, 네트워크 설계 변경, 대규모 데이터 마이그레이션과 같은 코드 경계 바깥의 실질적인 인프라 구축 비용은 줄여주지 못하는 한계가 있습니다.

03

Key Concepts

Concept · 01

포트와 어댑터 (Ports and Adapters)

핵심 비즈니스 로직(도메인)이 기술적 외부 요인(데이터베이스, 클라우드 SDK 등)에 직접 의존하지 않고 추상 인터페이스인 포트에만 의존하며, 구체적인 기술은 어댑터를 통해 주입받도록 격리하는 아키텍처 원칙입니다.

  • 파일 저장을 수행하는 비즈니스 요건을 Port 계약으로 정의함
  • AWS S3 전용 구현체와 국내 CSP 오브젝트 스토리지용 구현체를 각각 Adapter 형태로 구성함
Concept · 02

의존성 격리 (Dependency Isolation)

도메인 또는 비즈니스 유스케이스 모듈이 외부 기술 벤더의 라이브러리나 SDK 모듈을 직접 가져오지 못하도록 빌드 규칙과 아키텍처 규칙을 사용해 소스코드 수준에서 물리적으로 통제하는 기법입니다.

  • 수백 개의 서비스 모듈 중 최상위 모듈에만 SDK 의존성 버전을 모아 선언적으로 관리함
  • 도메인 코드 내에 com.amazonaws 패키지 경로를 가진 임포트가 존재하지 않도록 보장함
Concept · 03

S3 호환 API (S3-compatible API)

AWS S3가 제공하는 데이터 처리 표준 RESTful 규격을 다른 벤더가 자사 스토리지 제품군에 동일하게 적용하여 제공하는 표준 인터페이스 방식입니다.

  • 국내 CSP 스토리지가 S3 API를 지원함으로써 동일한 드라이버 클라이언트를 사용해 전환 작업의 복잡도를 낮춤