---
category: Dev
tags: [Architecture, Design Patterns, SOLID, Uncle Bob]
title: Clean Architecture
description: 프레임워크 독립성과 도메인 중심 설계를 통해 소프트웨어의 유지보수성과 테스트 용이성을 극대화하는 계층형 아키텍처
last_updated: 2026-05-02
---

# Clean Architecture

## 📌 Brief Summary
클린 아키텍처(Clean Architecture)는 로버트 C. 마틴(Robert C. Martin)이 제안한 설계 원칙으로, 시스템의 핵심 비즈니스 로직을 외부 프레임워크, 데이터베이스, UI 등 기술적 세부 사항으로부터 분리하는 것을 목표로 합니다. 시스템을 동심원 형태의 계층으로 나누고, **의존성의 방향이 항상 안쪽(도메인)으로만 향하게 하는 의존성 규칙(Dependency Rule)**을 적용하여, 기술 스택이 변경되더라도 핵심 로직은 영향을 받지 않도록 보호합니다.

---

## 📖 Core Content

### 1. 동심원 계층 구조
시스템은 추상화 수준에 따라 크게 4가지 계층으로 나뉩니다.

*   **Entities (엔티티):** 가장 안쪽 원으로, 핵심 비즈니스 규칙과 데이터를 캡슐화합니다. 특정 애플리케이션의 변경에 영향을 받지 않는 가장 일반적이고 고수준의 규칙입니다.
*   **Use Cases (유스케이스):** 애플리케이션에 특화된 비즈니스 규칙을 포함합니다. 엔티티 간의 데이터 흐름을 조정하며, 시스템의 동작(동작 시나리오)을 정의합니다.
*   **Interface Adapters (인터페이스 어댑터):** 외부 형식(DB, 웹)과 유스케이스/엔티티가 이해할 수 있는 내부 형식 사이를 번역합니다. Controller, Presenter, Repository 구현체가 여기에 속합니다.
*   **Frameworks & Drivers (프레임워크 및 드라이버):** 가장 바깥쪽 계층으로, 데이터베이스, 웹 프레임워크, UI 도구 등 구체적인 기술들이 위치합니다. 이들은 언제든 교환 가능한 '세부 사항'으로 취급됩니다.

### 2. 의존성 규칙 (The Dependency Rule)
*   **안쪽으로의 의존성:** 소스 코드 의존성은 반드시 안쪽(고수준 정책)으로만 향해야 합니다.
*   **격리:** 안쪽 원(도메인)은 바깥쪽 원(프레임워크, DB)에 대해 어떤 지식도 가져서는 안 됩니다. 바깥쪽 원에서 선언된 함수, 클래스, 변수 등을 안쪽 원에서 언급해서는 안 됩니다.

### 3. 실전 적용 사례 (Flutter & NestJS)
*   **Flutter:** `Presentation` (UI/State), `Domain` (Entity/UseCase), `Data` (Repository impl/DataSource) 계층으로 명확히 분리하여 멀티 플랫폼 대응력을 높입니다.
*   **NestJS:** 모듈별로 계층을 분리하고, 인터페이스 주입을 통해 서비스 로직이 데이터베이스 라이브러리(TypeORM, Prisma)에 직접 의존하지 않도록 설계합니다.

---

## ⚖️ Trade-offs & Caveats

### ✅ Benefits
*   **프레임워크 독립성:** 프레임워크를 도구로 사용하며, 시스템을 프레임워크의 제약 사항에 끼워 맞추지 않습니다.
*   **테스트 용이성:** UI, DB, 웹 서버 등 외부 요소 없이도 비즈니스 로직을 테스트할 수 있습니다.
*   **UI/DB 독립성:** 비즈니스 로직 변경 없이 UI를 웹에서 모바일로, DB를 SQL에서 NoSQL로 교체할 수 있습니다.

### ⚠️ Challenges
*   **과도한 추상화:** 소규모 프로젝트에서는 단순한 기능을 위해 너무 많은 클래스와 인터페이스를 만들어야 하므로 생산성이 저하될 수 있습니다 (Overkill).
*   **데이터 변환 비용:** 각 계층을 통과할 때마다 데이터를 변환(Mapping)해야 하므로 런타임 오버헤드와 개발 공수가 증가합니다.

---

## 🔗 Knowledge Connections

### Related Concepts
*   [[Hexagonal_Architecture]]: 클린 아키텍처와 철학을 공유하며, 포트와 어댑터를 통해 경계를 정의합니다.
*   [[Domain_Driven_Design]]: 엔티티와 유스케이스를 도출하는 강력한 방법론입니다.
*   [[SOLID_Principles]]: 특히 의존성 역전 원칙(DIP)이 클린 아키텍처의 핵심 메커니즘입니다.
*   [[Onion_Architecture]]: 인프라를 외곽으로 밀어내는 유사한 구조의 아키텍처입니다.

### Practical Application Contexts
*   **Long-term Maintenance:** 대규모 시스템에서 기술 부채를 관리하고 장기적인 안정성을 확보하기 위한 표준 가이드라인으로 활용됩니다.
*   **Legacy Migration:** 기존 코드를 새로운 기술 스택으로 이전할 때, 도메인 로직을 클린 아키텍처로 먼저 추출하는 전략이 유효합니다.

---

## 💡 Adjacent Topics
*   [[Test_Driven_Development]]: 외부 의존성이 제거된 클린 아키텍처는 TDD를 수행하기에 가장 이상적인 환경입니다.
*   [[BLoC_Pattern]]: Flutter에서 프리젠테이션 계층과 도메인 계층을 연결하는 대표적인 상태 관리 방식입니다.
*   [[Microservices]]: 개별 서비스의 내부 품질을 유지하기 위해 클린 아키텍처를 적용합니다.

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