117. 클린 아키텍처 (Clean Architecture)

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

본질: 클린 아키텍처 (Clean Architecture)는 로버트 마틴(Robert C. Martin)이 2012년 제안한 아키텍처로, 엔티티(Entity)→유스케이스(Use Case)→인터페이스 어댑터(Interface Adapter)→프레임워크 계층으로 구성된 동심원 구조에서 의존성이 항상 안쪽(도메인)을 향해야 한다는 의존성 규칙(Dependency Rule)을 핵심으로 한다.

가치: 비즈니스 규칙이 프레임워크, 데이터베이스, UI에 독립적이므로 어떤 기술 스택이 바뀌어도 핵심 비즈니스 로직은 변하지 않는다. 이는 시스템의 장기 생존성과 테스트 용이성을 동시에 확보한다.

판단 포인트: 클린 아키텍처의 가장 흔한 위반은 유스케이스나 엔티티 계층에 Spring 어노테이션이나 JPA 엔티티가 침투하는 것이다. "안쪽 원은 바깥쪽 원을 절대 알면 안 된다"는 단 하나의 규칙이 모든 판단의 기준이다.

Ⅰ. 개요 및 필요성

클린 아키텍처는 헥사고날, 어니언, DCI(Data, Context, Interaction) 등 여러 아키텍처 사상을 통합하고 명확한 이름과 구조로 정리한 것이다. 로버트 마틴은 "좋은 아키텍처는 프레임워크, 데이터베이스, 외부 에이전시로부터 시스템을 독립시켜야 한다"는 목표를 제시했다.

클린 아키텍처가 해결하는 핵심 문제는 기술적 선택이 비즈니스 결정에 종속되어야 함에도 현실에서는 종종 반대가 되는 현상이다. 특정 데이터베이스나 프레임워크를 먼저 결정하고 비즈니스 로직을 그 위에 맞추는 방식은 기술이 바뀔 때 비즈니스 로직도 함께 흔들리는 취약한 구조를 만든다.

┌─────────────────────────────────────────────────────────────┐
│        클린 아키텍처 동심원 구조                             │
├─────────────────────────────────────────────────────────────┤
│  ┌───────────────────────────────────────────────┐         │
│  │  프레임워크·드라이버 (Frameworks & Drivers)     │         │
│  │  ┌────────────────────────────────────────┐   │         │
│  │  │  인터페이스 어댑터 (Interface Adapters)  │   │         │
│  │  │  ┌────────────────────────────────┐    │   │         │
│  │  │  │  유스케이스 (Use Cases)          │    │   │         │
│  │  │  │  ┌──────────────────────────┐  │    │   │         │
│  │  │  │  │    엔티티 (Entities)      │  │    │   │         │
│  │  │  │  │  (핵심 비즈니스 규칙)     │  │    │   │         │
│  │  │  │  └──────────────────────────┘  │    │   │         │
│  │  │  └────────────────────────────────┘    │   │         │
│  │  └────────────────────────────────────────┘   │         │
│  └───────────────────────────────────────────────┘         │
│                                                             │
│  의존성 방향: 항상 ─────────────────────────────▶ 안쪽     │
└─────────────────────────────────────────────────────────────┘

의존성 규칙(Dependency Rule)은 "소스 코드 의존성은 항상 안쪽 원을 향해야 하며, 안쪽 원은 바깥쪽 원의 어떤 것도 알면 안 된다"는 단 하나의 규칙이다. 이 규칙 하나가 클린 아키텍처 전체를 정의한다.

📢 섹션 요약 비유: 양파를 까면 중심으로 갈수록 더 순수한 핵이 있다. 클린 아키텍처의 엔티티 계층은 가장 안쪽의 순수한 비즈니스 본질이며, 바깥 껍질(프레임워크)이 아무리 바뀌어도 핵심은 변하지 않는다.

Ⅱ. 아키텍처 및 핵심 원리

클린 아키텍처의 4개 계층은 각기 다른 변경 빈도와 이유를 가진다. 엔티티는 비즈니스 규칙이 바뀔 때만, 유스케이스는 애플리케이션 정책이 바뀔 때, 어댑터는 외부 인터페이스가 바뀔 때, 프레임워크 계층은 기술 선택이 바뀔 때 변경된다.

항목	설명	포인트
엔티티 (Entities)	핵심 비즈니스 규칙·도메인 모델 / 비즈니스 정책 변경	없음 (가장 안정)
유스케이스 (Use Cases)	애플리케이션 특화 비즈니스 규칙 / 기능 요구사항 변경	엔티티만
인터페이스 어댑터	외부↔유스케이스 데이터 변환 / UI, DB 인터페이스 변경	유스케이스
프레임워크·드라이버	웹, DB, 외부 서비스 연동 / 기술 스택 변경	어댑터

┌─────────────────────────────────────────────────────────────┐
│     경계를 넘는 데이터 흐름: DTO로 계층 격리                │
├─────────────────────────────────────────────────────────────┤
│  [Web Controller]                                           │
│       │ HTTP 요청 → Request DTO                             │
│       ▼                                                     │
│  [Use Case Interactor] ← Input Port interface               │
│       │ Domain Entity 사용                                  │
│       ▼                                                     │
│  [Output Port interface] → Presenter/Repository 어댑터       │
│       │ Response DTO                                        │
│       ▼                                                     │
│  [Presenter/View]                                           │
└─────────────────────────────────────────────────────────────┘

계층 경계를 넘을 때는 반드시 DTO (Data Transfer Object, 데이터 전달 객체)를 사용한다. 엔티티 객체가 어댑터 계층으로 그대로 전달되면 내부 도메인 구조가 외부에 노출되어 결합이 발생한다.

📢 섹션 요약 비유: 핵발전소(엔티티)의 핵반응 규칙은 발전 회사(유스케이스)가 바뀌어도, 전력망(어댑터)이 바뀌어도, 가정용 콘센트 규격(프레임워크)이 바뀌어도 변하지 않는다.

Ⅲ. 비교 및 연결

클린 아키텍처, 헥사고날 아키텍처, 어니언 아키텍처는 공통 철학을 공유하지만 용어와 강조점이 다르다.

비교 축	A	B
표현 방식	동심원 4계층	육각형 + 포트/어댑터 / 양파 계층
핵심 개념	의존성 규칙	포트와 어댑터 / 도메인 서비스 계층
공통점	도메인 중심, 의존성 안쪽 방향	동일 / 동일
특징	유스케이스 계층 명시적 강조	입출력 포트 명시적 분리 / 도메인 모델 계층 강조

세 아키텍처 모두 계층형의 "도메인이 인프라에 의존"하는 방향을 뒤집었다는 점에서 같은 뿌리를 가진다. 실무에서는 이들을 엄격히 구분하기보다 공통 원칙을 이해하고 팀에 맞게 적용하는 것이 더 중요하다.

📢 섹션 요약 비유: 클린, 헥사고날, 어니언은 모두 "도마뱀의 꼬리(인프라)를 잘라도 도마뱀(도메인)이 살아있어야 한다"는 철학을 서로 다른 그림으로 표현한 것이다.

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

클린 아키텍처 도입의 가장 현실적인 도전은 팀의 학습 곡선과 초기 개발 속도 저하다. DTO와 포트 인터페이스를 별도로 작성해야 하므로 단순 CRUD 기능도 여러 클래스가 필요하다. 이 비용이 도메인 복잡도와 장기 운영 기간에 비례하여 회수된다.

판단 체크리스트

엔티티 및 유스케이스 클래스에 프레임워크 어노테이션(@Entity, @Service, @Autowired)이 없는가?
계층 경계를 넘는 데이터가 도메인 엔티티가 아닌 DTO 형태인가?
유스케이스가 인터페이스(포트)를 통해 인프라를 호출하고 있는가?
순수 도메인 로직 테스트에 Spring 컨텍스트가 필요하지 않는가?
의존성 방향이 항상 안쪽 원을 향하는지 ArchUnit 등으로 자동 검증하는가?

📢 섹션 요약 비유: 헌법(엔티티·유스케이스)은 어느 정부(프레임워크)가 집권해도 바뀌지 않는다. 행정부(어댑터)가 바뀌어도 헌법의 핵심 가치는 보존된다.

Ⅴ. 기대효과 및 결론

클린 아키텍처를 적용하면 시스템의 "기술적 수명"이 비즈니스 수명을 따라가게 된다. 10년 후 데이터베이스가 바뀌어도, 웹 프레임워크가 세대교체를 해도 비즈니스 로직은 재작성 없이 살아남는다. 기술 부채(technical debt)가 비즈니스 핵심으로 침투하는 것을 원천적으로 차단한다.

한계는 작은 팀이나 단순한 CRUD 시스템에서의 오버엔지니어링 위험이다. 클린 아키텍처의 추상화 계층이 초기 개발 속도를 낮추므로, 도메인 복잡도가 낮거나 팀이 소규모인 경우 계층형 아키텍처로 시작하고 점진적으로 도입하는 것이 현실적이다.

미래 방향으로는 ① 모듈형 모놀리스(Modular Monolith)의 내부 구조로 클린 아키텍처 채택, ② AI 코드 생성 도구가 클린 아키텍처 스캐폴딩을 자동 생성, ③ 아키텍처 피트니스 함수로 의존성 규칙 위반 실시간 탐지가 발전하고 있다.

클린 아키텍처는 "소프트웨어를 기술의 노예가 아닌 비즈니스의 도구로 만드는 설계 철학"으로 기억해야 한다.

📢 섹션 요약 비유: 훌륭한 악기(비즈니스 로직)는 어느 음악홀(프레임워크)에서 연주하든 아름다운 소리를 낸다. 악기의 품질이 공연장에 의존해서는 안 된다.

📌 관련 개념 맵

[의존성 역전] → [클린 아키텍처] → [유스케이스 중심 설계] → [DDD 도메인 모델] → [MSA 내부 구조]

개념	연결 포인트
헥사고날 아키텍처	클린과 동일 원칙, 포트/어댑터로 표현
유스케이스	클린 아키텍처의 핵심 설계 단위
ArchUnit	의존성 규칙 위반을 테스트 코드로 자동 검증
DDD 엔티티	클린 아키텍처 엔티티 계층과 자연스럽게 대응

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

[기술 의존 비즈니스 로직 문제] → [클린 아키텍처 제안(마틴)] → [의존성 규칙·동심원 구조] → [DDD와 결합] → [MSA 서비스 내부 표준 구조] → [아키텍처 피트니스 함수 자동 검증]

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

케이크의 핵심 맛(비즈니스 규칙)은 어떤 예쁜 장식(프레임워크)을 올려도 변하지 않아야 해요.
클린 아키텍처는 장식을 아무리 바꿔도 케이크 안쪽(도메인)이 망가지지 않도록 만드는 방법이에요.
바깥(기술)이 안쪽(비즈니스)을 향해서만 의존하고, 안쪽은 바깥을 몰라야 해요!