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

flex가 파일 저장소를 AWS S3에서 국내 CSP 오브젝트 스토리지로 이전하면서 "Adapter만 바꾸면 된다"는 헥사고날 아키텍처의 약속이 실제로 성립하는 조건을 검증했다. 애플리케이션 코드 안에서는 그 문장이 맞았지만, 실제 이전 목록에는 Adapter 한 항목뿐이었고 인프라·배포·네트워크·데이터 이전이 대부분을 차지했다.

핵심 포인트

SDK가 조립 계층에만 격리돼 있어야 한다 — 도메인·서비스 모듈에 com.amazonaws 패키지가 없으면 교체 범위가 조립 계층에서 끝난다
Port 계약에 벤더 타입이 없어야 한다 — S3, Bucket, Region 같은 이름이 Port에 들어오면 Adapter 교체가 Port 수정으로 번지고 의존 도메인 전체가 영향을 받는다
클라우드별 차이는 Adapter 안에서 흡수한다 — 메타데이터 키 접두사, 서명 URL 유효기간 상한, 엔드포인트·인증 방식 세 가지를 Adapter 내부에서 처리했다
헥사고날이 보호하지 못하는 영역이 더 많다 — IaC, 배포 파이프라인, 네트워크, 데이터 이전은 경계 밖이라 Port·Adapter와 무관하게 손봐야 한다
파일 저장이 이전 난이도가 낮은 이유는 S3 호환 API 때문이다 — 메시지 큐는 대응 서비스가 없어 Port 계약 자체를 재설계해야 했다
이 구조는 이전 요건을 예상해서 만든 게 아니라 원칙을 일관 적용한 결과다 — 서비스 재제작 없이 Adapter 추가로 끝났다

상세 정리

이전 배경: HR SaaS 특성상 급여·근태 등 민감 데이터를 국내 인프라에서 보관해야 한다는 개인정보보호법·고객 계약 요건이 계기였다
조건 1 — SDK 격리: AWS SDK 의존성을 최상위 조립 계층에만 두고 도메인·서비스 모듈에는 AWS 패키지 이름이 없도록 빌드 규칙으로 물리적으로 막았다; SDK 버전도 한 곳에서 통합 관리해 수백 모듈이 같은 버전을 쓴다
조건 2 — Port 계약: 파일 저장 Port는 키·바이트·URL만 주고받고 S3, Bucket, Region 같은 AWS 용어가 없다; Port에 벤더 타입이 한 번 들어오면 Adapter 교체가 Port 수정으로 번지고 의존 도메인 전체가 영향받는다
조건 3 — Adapter 내 흡수 세 가지: (1) 메타데이터 키 접두사 — AWS는 자동 추가하지만 국내 CSP는 아니라 Adapter가 직접 처리, (2) 서명 URL 유효기간 상한 — 벤더마다 달라 Adapter가 요청값을 상한선으로 자름, (3) 엔드포인트·인증 — 설정 프로퍼티 한 줄로 Adapter를 교체
실제 이전 목록: Adapter 1건, IaC 재작성·배포 파이프라인 수정·네트워크 재설계·기존 데이터 이전이 나머지; 일정 대부분이 애플리케이션 코드 바깥에서 나왔다
영역별 난이도 비교: 파일 저장(낮음, S3 호환 API) → 관계형 DB·캐시(낮음) → 비밀 관리·관측(중간) → 메시지 큐(높음, 대응 서비스 없어 Port 재설계 필요)
얻은 것: 어느 클라우드를 향해도 빌드 산출물이 같은 한 벌의 애플리케이션 코드; 저장 백엔드가 바뀌어도 도메인 서비스는 한 줄도 건드리지 않았다
문장의 조건: "Adapter만 바꾸면 된다"는 SDK가 조립 계층에만 있고 Port 계약에 벤더 타입이 없다는 두 전제가 갖춰졌을 때만 성립한다; 이 조건은 이전 전에 이미 만들어져 있어야 한다

왜 읽나멀티 클라우드 전환·벤더 교체를 앞두고 있는 백엔드·아키텍처 엔지니어에게 헥사고날이 실제로 보호하는 범위와 그 전제 조건을 실전 사례로 확인할 수 있다.

flex 블로그

원문은 여기서 이어서 읽을 수 있어요

원문 읽기

읽음 (0)

·takedown 요청

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

이 글과 비슷한

일관성이 새로운 지연이다: 데이터 레이어에서의 AI

사람도 에이전트도, 덜 읽을수록 더 잘 고칩니다

데이터 거주 요건을 충족하는 재해 복구 전략