클린 아키텍처 프레임워크
비즈니스 규칙이 프레임워크, 데이터베이스, 전송 메커니즘과 무관하게 독립성을 유지하도록 소프트웨어를 구조화하는 훈련된 접근 방식입니다. 시스템 아키텍처를 설계하거나, 모듈 경계를 검토하거나, 의존성 관리에 대해 조언할 때 이 원칙을 적용하십시오.
핵심 원칙
소스 코드 의존성은 반드시 안쪽(고수준 정책)을 가리켜야 합니다. 내부 원에 있는 어떤 것도 외부 원에 대해 알 수 없습니다. 이 단일 규칙은 테스트 가능하고 프레임워크, UI, 데이터베이스 및 모든 외부 요소로부터 독립적인 시스템을 만듭니다. 비즈니스 규칙이 중요합니다. 데이터베이스, 웹 프레임워크, 전송 메커니즘은 세부사항일 뿐입니다. 세부사항이 정책에 의존하면 결정을 미루고, 구현을 교체하며, 비즈니스 로직을 고립된 상태에서 테스트할 수 있습니다.
점수
목표: 10/10. 아키텍처가 충족하는 일곱 가지 Quick Diagnostic 행 각각에 대해 1점을 부여하고(0-7), 이를 0-10 구간으로 매핑합니다. 6-7개 충족 = 9-10 (의존성 규칙 준수, 비즈니스 로직이 프레임워크 및 DB와 독립적); 4-5개 = 6-8 (핵심은 테스트 가능하지만 일부 세부사항이 안쪽으로 누출됨); 2-3개 = 3-5 (프레임워크나 영속성이 구조를 지배함); 0-1개 = 0-2 (경계 없음 — 비즈니스 규칙이 컨트롤러와 ORM 모델에 존재). 점수, 실패한 진단 행, 그리고 각각을 수정하기 위해 필요한 구체적인 역전 방향을 보고하십시오.
1. 의존성 규칙과 동심원
핵심 개념: 아키텍처를 동심원으로 구성합니다. 가장 안쪽에 엔터티(엔터프라이즈 비즈니스 규칙), 그 다음에 유스 케이스(애플리케이션 비즈니스 규칙), 그 다음에 인터페이스 어댑터, 가장 바깥쪽에 프레임워크 및 드라이버를 배치합니다. 소스 코드 의존성은 항상 안쪽을 가리킵니다.
왜 동작하는가: 고수준 정책이 저수준 세부사항에 의존하지 않으면 비즈니스 로직을 건드리지 않고 데이터베이스, 웹 프레임워크, API 스타일을 교체할 수 있습니다. 시스템은 스택에서 가장 변동성이 큰 부분에 탄력적으로 대응하게 됩니다.
핵심 통찰:
- 내부 원은 외부 원의 이름을 언급할 수 없습니다. 외부의 클래스, 함수, 변수, 데이터 형식을 사용할 수 없습니다.
- 경계를 넘는 데이터는 내부 원에 가장 편리한 형태여야 하며, 외부 원이 강요해서는 안 됩니다.
- 의존성 역전(인터페이스는 안쪽에서 정의되고 바깥쪽에서 구현됨)이 규칙을 강제하는 메커니즘입니다.
- 원의 개수는 고정되어 있지 않습니다. 일반적으로 네 개이며, 규칙은 동일하게 유지됩니다.
- 프레임워크는 세부사항이지 아키텍처가 아닙니다. 가장 바깥쪽 원에 속합니다.
코드 적용:
| 맥락 | 패턴 | 예시 |
|---|---|---|
| 레이어 방향 | 내부 원이 인터페이스를 정의하고 외부가 구현 | UserRepository 인터페이스는 유스 케이스에; PostgresUserRepository는 어댑터에 |
| 데이터 교차 | DTO가 경계를 넘고 ORM 엔터티는 넘지 않음 | 유스 케이스는 UserResponse DTO를 반환하고, ActiveRecord 모델은 반환하지 않음 |
| 의존성 방향 | 임포트 화살표는 항상 안쪽을 가리킴 | 컨트롤러가 유스 케이스를 임포트; 유스 케이스는 컨트롤러를 임포트하지 않음 |
내부 원 임포트가 바깥쪽을 가리킬 때 네 원 코드 설명, 데이터 교차 규칙, 그리고 이를 수정하기 위한 네 단계 의존성 역전 절차를 확인하려면 references/dependency-rule.md를 참조하십시오.
2. 엔터티와 유스 케이스
핵심 개념: 엔터티는 엔터프라이즈 전반의 비즈니스 규칙(소프트웨어가 없어도 존재할 규칙)을 캡슐화합니다. 유스 케이스는 엔터티와의 데이터 흐름을 조율하는 애플리케이션 특화 규칙을 포함합니다.
왜 동작하는가: 비즈니스가 수행하는 일(엔터티)과 애플리케이션이 이를 조율하는 방법(유스 케이스)을 분리하면 엔터티를 여러 애플리케이션에서 재사용하고, 핵심 비즈니스 규칙을 변경하지 않고 애플리케이션 동작을 변경할 수 있습니다.
핵심 통찰:
- 엔터티는 데이터베이스 행이 아닙니다. 중요한 비즈니스 규칙을 캡슐화하는 객체 또는 순수 함수입니다.
- 유스 케이스는 요청 모델을 받고 응답 모델을 반환합니다. 프레임워크 객체는 절대 사용하지 않습니다.
- 각 유스 케이스는 단일 애플리케이션 작업입니다(
CreateOrder,ApproveExpense). - 인터랙터 패턴: 유스 케이스 클래스는 입력 경계 인터페이스를 구현하고 출력 경계 인터페이스를 호출합니다.
- 유스 케이스의 변경이 엔터티에 영향을 주어서는 안 됩니다. 엔터티 변경은 유스 케이스에 전파될 수 있습니다.
코드 적용:
| 맥락 | 패턴 | 예시 |
|---|---|---|
| 엔터티 설계 | 중요한 비즈니스 규칙, 프레임워크 의존성 제로 | Order.calculateTotal()은 세금 규칙을 적용; HTTP에 대해 전혀 알지 못함 |
| 요청/응답 | 단순한 데이터 구조가 경계를 넘음 | CreateOrderRequest { items, customerId } — ORM 모델 없음 |
| 단일 책임 | 작업당 하나의 유스 케이스 | PlaceOrder, CancelOrder, RefundOrder를 별도의 클래스로 |
| 인터랙터 | 입력 포트를 구현하고 출력 포트를 호출 | PlaceOrderInteractor implements PlaceOrderInput |
인터랙터를 설계하거나 엔터티와 유스 케이스에 무엇이 속해야 하는지 결정할 때 엔터프라이즈 vs 애플리케이션 비즈니스 규칙에 대한 완전한 설명과 요청/응답 모델 예시를 확인하려면 references/entities-use-cases.md를 참조하십시오.
3. 인터페이스 어댑터와 프레임워크
핵심 개념: 인터페이스 어댑터는 유스 케이스/엔터티에 편리한 형태의 데이터와 외부 기관이 요구하는 형태 간 변환을 수행합니다. 프레임워크와 드라이버는 가장 바깥쪽 계층이며 외부 세계와의 접착 코드입니다.
왜 동작하는가: 웹 프레임워크, ORM, 메시지 큐가 외부 원에 국한되면 이들을 교체하는 것이 국소적인 변경이 됩니다. 데이터베이스는 세부사항이고, 웹은 세부사항입니다. 세부사항은 비즈니스 규칙에 플러그인처럼 연결되어야 하며, 애플리케이션의 뼈대가 되어서는 안 됩니다.
핵심 통찰:
- 컨트롤러는 HTTP를 유스 케이스 입력으로 변환합니다. 프리젠터는 유스 케이스 출력을 뷰 모델로 변환합니다.
- 게이트웨이는 유스 케이스가 정의한 리포지토리 인터페이스를 구현합니다. 내부 원이 계약을 정의하고 외부가 이를 충족합니다.
- 비즈니스 규칙은 데이터가 SQL, NoSQL, 플랫 파일 중 어디에 있는지, 또는 전송이 HTTP인지 결코 알지 못합니다.
- 프레임워크를 의심하십시오. 프레임워크는 여러분이 결합되기를 원합니다. 팔 길이만큼 거리를 두십시오.
코드 적용:
| 맥락 | 패턴 | 예시 |
|---|---|---|
| 컨트롤러 | 전달 메커니즘 → 유스 케이스 입력 | OrderController.create(req)가 CreateOrderRequest를 구성하고 인터랙터 호출 |
| 프리젠터 | 유스 케이스 출력 → 뷰 모델 | OrderPresenter.present(response)를 JSON/HTML 형식으로 변환 |
| 게이트웨이 | DB별로 구현된 리포지토리 인터페이스 | SqlOrderRepository implements OrderRepository |
| 프레임워크 경계 | 프레임워크가 안쪽을 호출하고, 그 반대는 없음 | Express 라우트 핸들러가 컨트롤러를 호출; 컨트롤러는 Express를 임포트하지 않음 |
컨트롤러, 프리젠터, 게이트웨이를 연결하거나 데이터베이스/웹이 세부사항임을 주장할 때 플러그인 아키텍처와 프레임워크를 가장자리로 국한시키는 방법을 확인하려면 references/adapters-frameworks.md를 참조하십시오.
4. 컴포넌트 원칙
핵심 개념: 컴포넌트는 배포 단위입니다. 세 가지 응집 원칙이 컴포넌트 내부의 내용을 규율하고, 세 가지 결합 원칙이 컴포넌트 간의 관계를 규율합니다.
왜 동작하는가: 잘못 구성된 컴포넌트는 하나의 변경이 관련 없는 코드의 재배포를 강제하는 파급 효과를 만듭니다. 원칙은 변경을 국소화하고 릴리스를 독립적으로 유지합니다.
핵심 통찰:
- REP (재사용/릴리스 등가): 컴포넌트의 클래스는 단위로 버전 관리 및 릴리스가 가능해야 함
- CCP (공통 폐쇄): 동일한 이유로 동시에 변경되는 클래스는 함께 속함 — 컴포넌트를 위한 SRP
- CRP (공통 재사용): 사용하지 않는 클래스에 의존하도록 강요하지 말 것
- ADP (비순환 의존성): 컴포넌트 그래프에 순환이 없어야 함 — DIP 또는 새 컴포넌트로 순환을 끊을 것
- SDP (안정된 의존성): 안정성 방향으로 의존할 것
- SAP (안정된 추상화): 안정적인 컴포넌트는 추상적이어야 하고, 불안정한 컴포넌트는 구체적이어야 함
코드 적용:
| 맥락 | 패턴 | 예시 |
|---|---|---|
| 컴포넌트 그룹화 | 함께 변경되는 클래스 그룹화 (CCP) | 모든 주문 관련 유스 케이스를 하나의 컴포넌트에 |
| 순환 끊기 | DIP 적용하여 의존성 가장자리 역전 | 인터페이스를 새 컴포넌트로 추출하여 순환 끊기 |
| 안정성 메트릭 | 불안정성 I = Ce / (Ca + Ce) | 많은 수신, 발신 의존성 없음 → I가 0에 가까움 (안정적) |
클래스를 배포 가능한 컴포넌트로 그룹화하거나 의존성 순환을 끊을 때, REP, CCP, CRP, ADP, SDP, SAP 각각을 불안정성 메트릭과 함께 확인하려면 references/component-principles.md를 참조하십시오.
5. SOLID 원칙
핵심 개념: 다섯 가지 클래스 및 모듈 수준 원칙 — 단일 책임, 개방-폐쇄, 리스코프 치환, 인터페이스 분리, 의존성 역전 — 의존성 규칙을 가능하게 하는 중간 수준의 구성 요소입니다.
왜 동작하는가: 각 원칙은 의존성이 잘못되는 특정 방식을 다루어, 코드베이스를 레거시 악몽으로 만드는 경직성, 취약성, 부동성을 방지합니다.
핵심 통찰:
- SRP: 모듈은 변경 이유가 하나여야 함 — 하나의 액터를 제공(단순히 "하나의 일"을 하는 것이 아님)
- OCP: 기존 코드를 수정하지 않고 새 코드를 추가하여 동작을 확장 — 전략 및 플러그인 패턴
- LSP: 서브타입은 클라이언트가 알 필요 없이 기본 인터페이스를 통해 사용 가능해야 함 — 예외적인 예외나 무시된 메서드로 위반됨
- ISP: 클라이언트는 사용하지 않는 메서드에 의존해서는 안 됨 — 거대 인터페이스는 불필요한 결합을 만듦
- DIP: 고수준 모듈과 저수준 모듈 모두 고수준 모듈이 정의한 추상화에 의존해야 함
코드 적용:
| 맥락 | 패턴 | 예시 |
|---|---|---|
| SRP 위반 | 클래스가 여러 액터를 제공 | Employee가 급여(CFO), 보고(COO), 영속성(CTO) 처리 |
| 전략을 통한 OCP | 새 동작을 새 클래스로 추가 | ExpressShipping이 ShippingStrategy 구현; Order는 수정되지 않음 |
| LSP 위반 | 서브타입이 예상된 동작 변경 | Square extends Rectangle이 setWidth()/setHeight() 계약 위반 |
| ISP 적용 | 거대 인터페이스를 역할 인터페이스로 분할 | 하나의 MultiFunctionDevice 대신 Printer, Scanner, Fax |
| DIP 배선 | 고수준이 인터페이스 정의; 저수준이 구현 | OrderService는 StripeClient가 아닌 PaymentGateway에 의존 |
특정 클래스에 SRP/OCP/LSP/ISP/DIP를 적용하거나 위반 사항을 진단할 때, 각 원칙을 코드 예제와 방지하는 악취와 함께 확인하려면 references/solid-principles.md를 참조하십시오.
6. 경계와 경계 해부학
핵심 개념: 경계는 중요한 것과 세부사항 사이의 선으로, 다형성을 통해 구현됩니다. 의존성은 안쪽을 가리키며 교차하고, 제어 흐름은 양방향으로 교차할 수 있습니다.
왜 동작하는가: 모든 경계는 결정을 미루거나 구현을 교체할 수 있는 옵션을 제공합니다. 전략적 경계 배치는 시스템이 수년간 유지 관리하기 즐거운지 고통인지를 결정합니다.
핵심 통찰:
- 완전한 경계는 양쪽에서 상호 인터페이스를 사용합니다. 부분적 경계는 더 단순한 전략이나 퍼사드를 사용합니다.
- Humble Object 패턴: 경계 코드를 테스트하기 어려운 부분(경계 근처)과 테스트하기 쉬운 부분(로직)으로 분할합니다.
- 서비스가 자동으로 아키텍처 경계가 되는 것은 아닙니다. 공유된 거대 데이터 모델을 가진 마이크로서비스는 네트워크 호출이 있는 모놀리스입니다.
- 테스트는 가장 고립된 컴포넌트입니다. 안쪽에 의존하고, 아무도 테스트에 의존하지 않습니다.
- 조기 경계는 비용이 많이 들지만, 경계가 없는 것도 마찬가지입니다. 변동 가능성이 있는 지점에 경계를 그리십시오.
코드 적용:
| 맥락 | 패턴 | 예시 |
|---|---|---|
| 완전 vs. 부분 경계 | 상호 포트, 또는 단일 전략 | 유스 케이스가 PlaceOrderInput/PlaceOrderOutput 정의; 더 단순한 경우 ShippingStrategy 사용 |
| Humble Object | 테스트 가능한 로직을 인프라에서 분리 | PresenterLogic(테스트 가능)이 ViewModel 생성; View(humble)가 렌더링 |
| 플러그인으로서의 Main | 구성 루트가 시스템을 조립 | main()이 모든 구체적 구현을 배선하고 앱 시작 |
경계를 그릴 위치 결정, 완전 vs. 부분 경계 선택, Humble Object 패턴 적용 시, 서비스를 경계로, 테스트 경계, 그리고 궁극적인 플러그인으로서의 Main을 포함하여 확인하려면 references/boundaries.md를 참조하십시오.
일반적인 실수
| 실수 | 실패 이유 | 수정 |
|---|---|---|
| ORM이 비즈니스 로직으로 누출 | 엔터티가 스키마에 결합; DB 변경이 비즈니스 규칙을 재작성 | 도메인 엔터티를 영속성 모델과 분리; 어댑터 계층에서 매핑 |
| 컨트롤러의 비즈니스 규칙 | HTTP 없이 테스트 불가; 엔드포인트 간 중복 | 로직을 유스 케이스 인터랙터로 이동; 컨트롤러는 번역 및 위임만 수행 |
| 프레임워크 우선 아키텍처 | 프레임워크가 구조를 결정; 교체 시 재작성 필요 | 프레임워크를 플러그인으로 취급; 코드를 비즈니스 기능별로 구조화 |
| 순환 컴포넌트 의존성 | 변경이 예측 불가능하게 파급; 독립적 릴리스 불가 | DIP 적용 또는 공유 추상화 컴포넌트 추출 |
| 기능당 하나의 거대 유스 케이스 | 비대해진 수천 줄의 오케스트레이터 | 집중된 단일 작업 유스 케이스로 분할 |
| "간단하니까" 경계 건너뛰기 | 결합이 조용히 누적되다가 막대한 비용 발생 | 변동 가능성이 있는 지점에 사전에 경계를 그림 |
| 마이크로서비스 = 자동으로 좋은 아키텍처 | 분산 모놀리스는 깨끗한 모놀리스보다 더 나쁨 | 서비스 내부와 서비스 간에 의존성 규칙 적용; 서비스는 배포 경계일 뿐, 아키텍처 경계가 아님 |
빠른 진단
| 질문 | 아니오인 경우 | 조치 |
|---|---|---|
| DB, 웹 서버, 프레임워크 없이 비즈니스 규칙을 테스트할 수 있습니까? | 규칙이 인프라에 결합됨 | 인터페이스 뒤에 엔터티와 유스 케이스 추출; 외부 계층 모킹 |
| 모든 소스 의존성이 안쪽을 가리킵니까? (외부 원이 내부 원을 임포트하지 않음) | 의존성 역전 위반 | DIP 적용: 내부 원이 소유한 인터페이스에 의존하도록 외부 원 변경 |
| 데이터가 경계를 넘을 때 내부 원에 편리한 간단한 구조를 사용합니까? | ORM/프레임워크 객체가 안쪽으로 누출됨 | 전용 DTO/요청 모델 도입; 어댑터 계층에서 매핑 |
| 유스 케이스가 단일 작업을 수행하고 프레임워크에 독립적입니까? | 유스 케이스가 여러 책임을 가지거나 프레임워크에 결합됨 | 각 유스 케이스를 단일 작업으로 리팩토링; 프레임워크 임포트 제거 |
| 엔터티가 프레임워크/ORM에 대한 의존성 없이 중요한 비즈니스 규칙만 포함합니까? | 엔터티가 영속성 또는 UI 세부사항과 혼합됨 | 진정한 비즈니스 규칙만 남도록 엔터티에서 인프라 관심사 분리 |
| 컴포넌트 의존성 그래프에 순환이 없습니까? | 순환 존재 | 순환 끊기를 위해 DIP 또는 새 컴포넌트 적용 |
| DB, 웹, 메시징 등을 교체할 때 비즈니스 규칙을 변경해야 합니까? | 세부사항이 아키텍처를 오염시킴 | 외부 원에 프레임워크/DB 코드 국한; 내부 원은 인터페이스를 통해 통신 |
참조
- 의존성 규칙 — 내부 원 임포트가 바깥쪽을 가리킬 때 네 원 코드 설명, 데이터 교차 규칙, 의존성 역전 절차
- 엔터티 및 유스 케이스 — 엔터프라이즈 vs 애플리케이션 비즈니스 규칙, 요청/응답 모델
- 어댑터 및 프레임워크 — 컨트롤러, 프리젠터, 게이트웨이, 프레임워크 국한
- 컴포넌트 원칙 — REP, CCP, CRP, ADP, SDP, SAP, 불안정성 메트릭
- SOLID 원칙 — SRP, OCP, LSP, ISP, DIP 코드 예제
- 경계 — 전체/부분 경계, Humble Object, Main을 플러그인으로