---
category: Unified
tags: [auto-consolidated, technical-documentation]
title: [[Onion Architecture]]
last_updated: 2026-05-02
---

# [[Onion Architecture]]

## 📌 Brief Summary
양파 아키텍처(Onion Architecture)는 관심사의 분리와 의존성 역전 원칙을 극대화하여 도메인 모델을 아키텍처의 중심에 배치하는 도메인 중심 설계 패턴입니다. 비즈니스 로직을 외부 기술(데이터베이스, UI 등)로부터 완전히 분리하고, 모든 의존성이 바깥쪽에서 안쪽(중심)으로만 향하도록 엄격한 계층 간 종속성 규칙을 준수합니다. 헥사고날 아키텍처(Hexagonal Architecture)의 개념을 확장하여 고안되었으며, 이후 클린 아키텍처(Clean Architecture)로 발전하는 징검다리 역할을 한 마이크로 레벨의 아키텍처 설계 방식입니다.

## 📖 Core Content
*   **도메인 모델의 중심 배치 및 의존성 역전:** 양파 아키텍처는 핵심 비즈니스 로직(도메인 모델)을 아키텍처의 정중앙에 둡니다. 외부 계층(데이터베이스, 웹 프레임워크 등)에서 내부 계층으로만 의존성이 향하도록 엄격한 종속성 규칙을 준수하여 구현됩니다. [1]
*   **기술 및 인프라로부터의 완벽한 독립:** 비즈니스 로직은 외부의 데이터베이스나 사용자 인터페이스(UI)에 대해 전혀 알지 못합니다. 대신, 추상화된 포트(Port)나 인터페이스를 통해 소통하며 실제 구현체는 외부 계층에서 어댑터(Adapter)를 통해 주입됩니다. 이를 통해 기술 스택이 변경되더라도 핵심 로직을 수정할 필요가 없으며 데이터베이스 없이도 완벽한 테스트가 가능합니다. [1]
*   **아키텍처의 진화와 위치:** 헥사고날 아키텍처가 먼저 등장하여 포트와 어댑터의 개념을 정립했다면, 양파 아키텍처는 이를 확장하여 더 많은 계층(layers)을 구조화한 패턴입니다. 이후 이 개념들은 클린 아키텍처로 더욱 정제되었습니다. [2]
*   **거시적 아키텍처 내의 미시적(Micro) 설계:** 전통적인 계층형 아키텍처(Layered Architecture)가 시스템 구조나 팀을 나누는 거시적(Macro) 수준의 아키텍처라면, 양파 아키텍처는 그중 '비즈니스 계층' 내부를 어떻게 견고하게 설계할 것인지에 초점을 맞춘 미시적(Micro) 설계 패턴으로 간주됩니다. [3]

## ⚖️ Trade-offs & Caveats
*   **보일러플레이트 코드 증가:** 의존성이 외부에서 내부로만 향하도록 계층을 분리하고 캡슐화하는 과정에서, 양파의 각 계층마다 유사한 가치 객체(Value Objects)나 POJO(Plain Old Java Object)를 중복해서 구현해야 하는 부작용이 발생합니다. 처음에는 각 패키지에 똑같은 코드를 복사하여 붙여넣는 것처럼 보일 수 있으며, 이로 인해 초기 보일러플레이트 코드가 증가합니다. [2]
*   **구조적 복잡성:** 헥사고날 아키텍처에 비해 계층이 더 세분화되어 있어, 단일 작업을 수행하는 단순한 애플리케이션에 적용하기에는 지나친 오버엔지니어링(Over-engineering)이 될 수 있습니다. [2]
*   *소스에 관련 정보가 부족합니다.* (양파 아키텍처만의 독자적인 세부 제약 사항이나 성능적 한계에 대한 추가적인 데이터는 소스 내에 제한적으로만 언급되어 있습니다.)

## 🔗 Knowledge Connections
### Related Concepts

#### [아키텍처/기반 기술]
*   [[Hexagonal Architecture]]
    *   연결 이유: 양파 아키텍처의 사상적 기반이 되는 가장 포괄적이고 먼저 등장한 도메인 중심 패턴입니다. [2]
    *   이 개념을 통해 더 깊게 이해할 수 있는 부분: 포트(Port)와 어댑터(Adapter)를 통해 내부 로직과 외부 인프라를 분리하는 핵심 메커니즘을 이해할 수 있습니다.
*   [[Clean Architecture]]
    *   연결 이유: 양파 아키텍처의 개념을 더욱 확장하여 세부적인 규율을 추가한 패턴입니다. [1, 2]
    *   이 개념을 통해 더 깊게 이해할 수 있는 부분: 양파 아키텍처에서 비롯된 의존성 규칙이 엔터프라이즈 환경에서 어떻게 최종적으로 정립되는지 비교 파악할 수 있습니다.
*   [[Layered Architecture]]
    *   연결 이유: 전통적인 아키텍처 패턴으로, 양파 아키텍처는 계층형 구조의 단점(데이터베이스 종속성)을 해결하기 위한 대안이자, 계층형 아키텍처의 비즈니스 계층 내부를 설계하는 방식으로 쓰입니다. [3]
    *   이 개념을 통해 더 깊게 이해할 수 있는 부분: 의존성이 위에서 아래로(프레젠테이션 -> 비즈니스 -> 데이터베이스) 흐르는 방식과 밖에서 안으로 흐르는 양파 아키텍처의 패러다임 차이를 명확히 이해할 수 있습니다.

### Deeper Research Questions
*   양파 아키텍처에서 여러 계층을 거치며 발생하는 데이터 모델(POJO)의 중복과 보일러플레이트 코드를 최소화할 수 있는 실용적인 매핑(Mapping) 전략은 무엇인가?
*   단순한 애플리케이션에서는 오버엔지니어링이 될 수 있는데, 프로젝트 도입 시 양파 아키텍처의 복잡성을 정당화할 수 있는 구체적인 비즈니스 로직의 복잡도 기준은 무엇인가?
*   조직 구조(Conway's Law)의 관점에서, 거시적 계층형 아키텍처와 미시적 양파 아키텍처를 결합할 때 개발 팀 간의 역할 분담과 협업 프로세스는 어떻게 설계해야 하는가?
*   양파 아키텍처 내에서 핵심 비즈니스 로직을 데이터베이스 연결 없이 독립적으로 테스트하기 위한 최적의 단위 테스트(Unit Test) 구성 방법은 무엇인가?
*   헥사고날, 양파, 클린 아키텍처가 근본적으로 유사한 아이디어를 공유한다면, 각 패턴이 구체적인 코드 레벨의 패키지 구조에 미치는 차이점론 무엇인가?

### Practical Application Contexts
*   **Implementation:** 핵심 비즈니스 로직을 프로젝트의 중심(내부 패키지)에 구현하고, 데이터베이스 저장이나 UI 표시에 대한 구체적인 코드는 가장 바깥쪽 계층에 구현한 뒤 의존성 주입(DI)을 통해 연결합니다.
*   **System Design:** 기술 스택이나 프레임워크가 시간이 지남에 따라 자주 변경될 가능성이 높거나, 복잡한 비즈니스 규칙을 장기적으로 안전하게 보호하고 유지보수해야 하는 현대적 시스템을 설계할 때 유용합니다.
*   **Operation / Maintenance:** 기술 종속성이 중앙 도메인 로직에 영향을 미치지 않기 때문에, 운영 중인 서비스의 외부 결제 API, 데이터베이스 벤더 등을 교체할 때도 시스템 코어의 수정을 최소화하여 유지보수 비용을 낮출 수 있습니다.
*   **Learning Path:** Layered Architecture의 강한 결합에 대한 문제점을 먼저 학습한 후, 의존성 역전 원칙(DIP)을 바탕으로 Hexagonal -> Onion -> Clean Architecture 순으로 진화하는 소프트웨어 설계의 흐름을 따라 학습하는 것이 좋습니다.
*   **My Project Relevance:** 클라우드 환경이나 마이크로서비스 내에서 각 서비스의 도메인 로직이 외부 통신 방식이나 데이터 저장 방식에 구애받지 않고 견고하게 동작해야 하는 부분을 구축할 때 직접적으로 활용할 수 있습니다.

### Adjacent Topics
*   [[Domain-Driven Design (DDD)]]
    *   확장 방향: 양파 아키텍처의 가장 중심이 되는 '도메인 모델'을 어떻게 도출하고 식별할 것인지, 비즈니스 영역(Bounded Context)을 어떻게 분할할 것인지에 대한 분석 및 설계 방법론으로 학습을 확장할 수 있습니다.

---
*Last updated: 2026-05-02*