118. 어니언 아키텍처 (Onion Architecture)

핵심 인사이트 (3줄 요약)

1. 본질: 어니언 아키텍처 (Onion Architecture)는 제프리 팔레르모(Jeffrey Palermo)가 2008년 제안한 아키텍처로, 양파 껍질처럼 도메인 모델을 가장 안쪽에 두고 바깥 계층이 안쪽 계층에만 의존하게 하여 인프라 의존성을 완전히 외부로 추방하는 설계다.
2. 가치: 도메인 서비스(Domain Service) 계층이 인프라(Infrastructure)로부터 완전히 분리되므로, 도메인 로직 테스트가 외부 의존성 없이 빠르게 실행되고 비즈니스 규칙의 순수성이 보장된다.
3. 판단 포인트: 어니언 아키텍처와 클린 아키텍처·헥사고날의 차이는 도메인 계층의 세분화 방식이다. 어니언은 도메인 모델, 도메인 서비스, 애플리케이션 서비스의 3단계로 도메인 내부를 더 구체적으로 구분한다.

Ⅰ. 개요 및 필요성

어니언 아키텍처는 전통적인 계층형 아키텍처에서 데이터 계층(데이터베이스)이 아키텍처의 기반으로 취급받는 문제를 해결하기 위해 등장했다. 데이터베이스를 중심에 두면 ORM 설계가 도메인 모델 설계보다 선행되어 비즈니스 로직이 데이터베이스 스키마에 종속되는 왜곡이 생긴다.

팔레르모는 "핵심은 도메인 모델이며, 인프라는 도메인이 필요로 하는 계약(인터페이스)을 구현하는 세부 사항"이라고 주장한다. 이 원칙을 양파 구조로 시각화하여, 가장 안정적인 것(도메인 모델)이 중심에, 가장 변하기 쉬운 것(인프라)이 외부에 위치하게 했다.

┌─────────────────────────────────────────────────────────────┐
│          어니언 아키텍처 계층 구조                            │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐    │
│  │  인프라 (Infrastructure): DB, UI, 외부 서비스        │    │
│  │  ┌─────────────────────────────────────────────┐   │    │
│  │  │  애플리케이션 서비스 (Application Services)  │   │    │
│  │  │  ┌─────────────────────────────────────┐   │   │    │
│  │  │  │  도메인 서비스 (Domain Services)     │   │   │    │
│  │  │  │  ┌────────────────────────────┐    │   │   │    │
│  │  │  │  │  도메인 모델 (Domain Model) │    │   │   │    │
│  │  │  │  │  Entity, Value Object      │    │   │   │    │
│  │  │  │  └────────────────────────────┘    │   │   │    │
│  │  │  └─────────────────────────────────────┘   │   │    │
│  │  └─────────────────────────────────────────────┘   │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
│  의존성 방향: 항상 바깥 → 안쪽 (외부가 내부를 의존)          │
└─────────────────────────────────────────────────────────────┘

인프라 계층의 Repository 구현체는 도메인 서비스 계층에 정의된 IRepository 인터페이스를 구현한다. 이 인터페이스 계약은 도메인이 소유하므로 인프라가 도메인을 향해 의존한다.

• 📢 섹션 요약 비유: 양파를 까면 층마다 새로운 껍질이 있고 가장 중심은 가장 순수한 핵이다. 바깥 껍질을 제거해도 안쪽 핵은 그대로다. 인프라라는 바깥 껍질을 바꿔도 도메인 핵심은 영향받지 않는다.

Ⅱ. 아키텍처 및 핵심 원리

어니언 아키텍처의 계층별 역할은 클린 아키텍처보다 도메인 내부를 더 세분화한다. 특히 도메인 모델과 도메인 서비스의 분리가 특징적이다.

┌─────────────────────────────────────────────────────────────┐
│      도메인 서비스와 애플리케이션 서비스의 역할 분리         │
├─────────────────────────────────────────────────────────────┤
│  [도메인 서비스] TransferDomainService                      │
│   - 이체 규칙 검증 (계좌 잔액 확인, 한도 확인)              │
│   - 순수 비즈니스 로직 (외부 의존 없음)                     │
│                                                             │
│  [애플리케이션 서비스] TransferApplicationService           │
│   - 트랜잭션 시작/커밋                                      │
│   - 알림 서비스 호출 (도메인 외 인프라 조율)                 │
│   - 이체 완료 이벤트 발행                                    │
└─────────────────────────────────────────────────────────────┘

도메인 서비스는 데이터베이스 트랜잭션이나 알림 발송 같은 인프라 관심사를 모른다. 이런 조율은 애플리케이션 서비스가 담당한다. 이 분리 덕분에 도메인 서비스는 순수 비즈니스 규칙만 담당하여 완전한 단위 테스트가 가능하다.

• 📢 섹션 요약 비유: 의사(도메인 서비스)는 진단과 처방이라는 순수 의료 행위만 한다. 서류 작성과 보험 청구(애플리케이션 서비스)는 행정 직원이, 약품 조달(인프라)은 약국이 담당한다.

Ⅲ. 비교 및 연결

어니언 아키텍처는 클린 아키텍처와 가장 유사하지만, 도메인 서비스와 애플리케이션 서비스를 명확히 구분한다는 점이 차이다.

DDD (Domain-Driven Design, 도메인 주도 설계)와 어니언 아키텍처는 자연스럽게 결합된다. DDD의 애그리게이트, 엔티티, 값 객체가 도메인 모델 계층에, 도메인 서비스가 도메인 서비스 계층에, 리포지토리 인터페이스도 도메인 서비스 계층에 정의된다.

• 📢 섹션 요약 비유: 어니언은 층이 선명하게 보이는 양파, 클린은 원을 그려 경계를 표시한 과녁, 헥사고날은 육각형 성벽이다. 표현은 달라도 모두 "도메인을 중심에 보호한다"는 같은 이야기를 한다.

Ⅳ. 실무 적용 및 기술사 판단

어니언 아키텍처에서 가장 중요한 실무 규칙은 Repository 인터페이스의 위치다. Repository 인터페이스는 도메인 서비스 계층에 정의되어야 하며, 인프라 계층의 JpaRepository가 이것을 구현한다. 만약 JpaRepository를 도메인 서비스에서 직접 사용하면 인프라가 도메인을 오염시킨다.

판단 체크리스트

1. Repository 인터페이스가 도메인 서비스 계층에 위치하는가?
2. 도메인 서비스 클래스에 트랜잭션 어노테이션(@Transactional)이 없는가?
3. 도메인 모델 클래스가 순수 Java/Kotlin으로만 작성되어 있는가?
4. 애플리케이션 서비스가 도메인 서비스를 조율하며 외부 인프라를 호출하는가?
5. 도메인 모델 단위 테스트에 인프라 Mock이 전혀 필요하지 않는가?

• 📢 섹션 요약 비유: 양파를 손질할 때 바깥 마른 껍질(인프라)은 벗겨내야 하지만 속의 층층 구조(도메인 계층)는 그대로 살아있어야 한다. 벗기다가 속까지 망가지면 요리가 안 된다.

Ⅴ. 기대효과 및 결론

어니언 아키텍처는 도메인 서비스의 순수성을 통해 비즈니스 규칙의 완전한 자동화 테스트를 가능하게 한다. 도메인 로직을 담당하는 팀이 인프라 팀과 완전히 독립적으로 개발하고 테스트할 수 있어 대형 팀의 병렬 개발 속도가 향상된다. 레거시 시스템의 인프라를 교체하는 프로젝트에서 도메인을 보호하면서 인프라만 점진적으로 교체하는 전략으로도 효과적이다.

한계는 학습 곡선과 도메인 서비스·애플리케이션 서비스의 경계 결정이 팀마다 달라질 수 있다는 점이다. 어떤 로직이 도메인 서비스고 어떤 것이 애플리케이션 서비스인지 판단하는 기준이 명확하지 않으면 계층 경계가 흐려진다.

미래 방향으로는 ① DDD와의 완전 통합으로 어니언 + DDD 구조가 마이크로서비스 내부 표준화, ② 어니언 계층 위반을 탐지하는 아키텍처 테스트 자동화, ③ 코드 생성 도구의 어니언 구조 자동 스캐폴딩이 발전하고 있다.

어니언 아키텍처는 "비즈니스의 본질(도메인)을 기술 세부 사항(인프라)으로부터 양파 껍질처럼 겹겹이 보호하는 설계"로 기억해야 한다.

• 📢 섹션 요약 비유: 아이를 보호하기 위해 여러 겹의 따뜻한 옷을 입히듯, 도메인 모델을 여러 계층(도메인 서비스→애플리케이션 서비스→인프라)이 겹겹이 감싸서 외부 변화로부터 보호한다.

📌 관련 개념 맵

[계층형 한계] → [어니언 아키텍처] → [DDD 도메인 모델] → [도메인 서비스·애플리케이션 서비스 분리] → [MSA 내부 구조]

📈 관련 키워드 및 발전 흐름도

[데이터베이스 중심 계층형 설계] → [어니언 아키텍처 제안(팔레르모)] → [도메인 서비스·애플리케이션 서비스 분리] → [DDD와 통합] → [클린·헥사고날과 수렴] → [MSA 서비스 내부 표준 구조]

👶 어린이를 위한 3줄 비유 설명

1. 양파는 껍질을 벗겨도 안에 또 껍질이 있고, 가장 안쪽이 제일 소중한 핵이에요.
2. 어니언 아키텍처는 도메인(핵심 비즈니스)을 가장 안쪽에, 기술(데이터베이스, 웹)을 바깥에 두는 구조예요.
3. 바깥 껍질(기술)이 바뀌어도 안쪽(비즈니스 규칙)은 그대로 남아있어요!