클린 아키텍처 핵심 가이드 - 파이썬으로 구현하는 좋은 소프트웨어 설계를 위한 클린 아키텍처(위키북스IT LEADERS시리즈43)

소프트웨어를 장기간 운영하고 개선하며 유지보수해본 개발자라면 코드 구조화의 중요성을 뼈저리게 느낀다. 동료가 쉽게 이해하고, 테스트가 용이하며, 변경에 강건한 코드는 단순히 기능이 동작하는 수준을 훨씬 넘어선다. 요즘처럼 생성형 AI로 코드를 빠르게 찍어낼 수 있는 시대에도 초기 구현 단계에서는 구조가 다소 느슨해도 동작은 하지만 실제 서비스로 출시하고 수년간 운영하려면 철저한 구조화 없이는 불가능하다.

 

《클린 아키텍처 핵심 가이드》는 장기 유지보수성과 비즈니스 민첩성을 동시에 확보하는 소프트웨어 설계의 본질을 다룬다. 로버트 C. 마틴의 클린 아키텍처를 중심축으로 삼아 이론 설명에 그치지 않고, 실무에서 바로 적용 가능한 풍부한 코드 예제를 제시하며 아키텍처 원칙을 구체적으로 구현하는 방법을 보여준다.

 

이 책을 읽으면 소프트웨어가 단순히 ‘동작하는 코드’가 아니라 비즈니스 목표와 요구 속성을 명확히 반영해야 하는 산물이며, 동시에 팀원 간 협업과 소통의 핵심 언어라는 점을 깨닫게 된다. 그동안 추상적으로만 느껴졌던 아키텍처 이론이 실제 코드와 함께 제시되면서 직관적으로 이해되고, 바로 자신의 프로젝트에 적용할 수 있는 수준으로 내면화된다.

 

특히 생성형 AI를 적극 활용하는 현재 개발 환경에서, 왜 개발자가 여전히 구조화를 주도해야 하는지, AI를 단순한 코드 생성기가 아닌 고품질 아키텍처를 만드는 강력한 조력자로 활용하는 방법까지 명확히 제시한다. 이 책은 클린 아키텍처를 배우는 데 그치지 않고, AI 시대에 개발자가 반드시 갖춰야 할 설계 감각과 실무 역량을 한 단계 끌어올리는 실질적인 지침서다.

[목 차]

 

 

▣ 01장: 좋은 소프트웨어 설계란 무엇이고, 왜 필요한가?

1.1 소프트웨어 아키텍처의 정의

__구조의 결정

__지식 공유

1.2 좋은 소프트웨어 아키텍처의 중요성

__소프트웨어의 상품적 가치

__구조의 우선순위

__변경 가능성의 본질

__비즈니스 관점에서의 가치

__민첩성을 위한 아키텍처의 진화

__미래를 대비한 설계

1.3 아키텍처에 영향을 주는 요소

__기능 요구사항

__제한 요소

__품질 속성

__아키텍처 설계의 기준

1.4 의도를 드러내는 아키텍처

__단순성과 지속성

__일관성의 중요성

__격리와 변경 관리

__살아있는 아키텍처

__변경에 대한 용기

1.5 아키텍처가 개발자에게 주는 영향

__변경의 명확성과 효율성

__개발자의 자신감과 만족도

__팀 협업의 향상

__장기적 생산성

1.6 정리

 

▣ 02장: 품질 속성

2.1 품질 속성의 정의와 역할

__품질 속성의 정의

__품질 속성의 역할

__정량적 요구사항의 중요성

2.2 품질 속성 시나리오와 예시

__품질 속성 시나리오의 구성

__주요 품질 속성 시나리오 예시

2.3 클린 아키텍처에서 중시하는 품질 속성

__테스트 용이성

__변경 용이성

2.4 품질 속성 간 트레이드오프

2.5 정리

 

▣ 03장: 소프트웨어 설계를 위한 핵심 개념과 기법

3.1 의존성이란?

3.2 다형성

__다형성의 올바른 활용

3.3 의존성 역전과 주입

3.4 관심사 분리

__관심사의 세 가지 범주

3.5 반드시 객체지향이어야 할까?

__객체지향적 구현

__함수형 프로그래밍 구현

__간단한 모듈 패턴 구현

3.6 정리

 

▣ 04장: 계층형 설계

4.1 계층형 아키텍처란?

4.1 계층형 아키텍처의 장점

__코드 가독성 향상

__관심사 분리로 수정 용이성 향상

__의존성 관리 용이

4.3 계층형 아키텍처의 구조와 호출 흐름

__구성 요소

__호출 흐름과 의존성 방향

4.4 계층형 아키텍처의 한계와 클린 아키텍처로의 전환 필요성

__데이터베이스 중심 설계

__싱크홀 안티패턴과 코드 중복

__테스트와 외부 요소 변경의 어려움

__비즈니스 로직 표현 부족

4.5 정리

 

▣ 05장: 클린 아키텍처란?

5.1 클린 아키텍처가 추구하는 것

__외부 요소 분리의 진정한 가치

__변화의 현실을 직시하다

__그런데 왜 하필 외부 요소의 변경에 집중할까?

5.2 클린 아키텍처의 품질 속성과 구현 방법

__테스트 용이성

__변경 용이성

__확장성

__협업과 가독성: 명확한 구조화

5.3 구성요소와 의존성 규칙

__각 계층의 역할과 책임

__의존성 규칙

__의존성 방향과 접근 제어

5.4 경계를 가로지르는 데이터

__호출 흐름과 데이터 정의의 관계

__데이터 정의 위치가 중요한 이유

__DTO 사용 전략

__DTO 설계 시 고려사항

5.5 왜 이해하기 어려웠을까?

__개념 자체의 복잡성

__관점의 혼재

__실전 예제의 부족과 구현 방식의 다양성

__용어의 비일관성

__실용적 접근의 필요성

5.6 정리

 

▣ 06장: 호출 흐름에 따른 각 구성 요소의 역할

__호출 흐름과 의존 방향의 구분

__호출 흐름의 중요성과 코드 예시의 필요성

__학생 성적 계산 프로그램 예제

6.1 프레임워크

__프레임워크의 호출 흐름 내 역할

__FastAPI를 사용한 프레임워크 구현

__다양한 인터페이스 지원

6.2 컨트롤러

__컨트롤러의 호출 흐름 내 역할

__컨트롤러 구현

__프레임워크와의 연결

__FastAPI 라우터에서 컨트롤러의 역할 수행

6.3 유스케이스

__유스케이스의 호출 흐름 내 역할

__유스케이스 구현

__유스케이스의 핵심 원칙

__추상화와 의존성 주입

__입력 및 출력 인터페이스

__FastAPI 라우터와의 연계

6.4 게이트웨이

__게이트웨이의 호출 흐름 내 역할

__게이트웨이 구현

__게이트웨이의 핵심 원칙

__인터페이스의 위치와 의존성 주입

__데이터 변환의 중요성

__외부 시스템과의 확장성

__게이트웨이 설계 시 고려사항

6.5 외부 요소

__외부 요소의 호출 흐름 내 역할

__코드 예시

__외부 요소의 핵심 원칙

__의존성 주입과의 연계

__ORM을 사용하는 경우

__게이트웨이와 외부 요소의 분리

__호출 흐름에서의 외부 요소

6.6 엔티티

__엔티티의 역할

__코드 예시

__엔티티 내부의 계층화

__유스케이스와의 관계

__엔티티 설계 시 고려사항

6.7 프레젠터

__프레젠터의 구성 요소

__프레젠터와 유스케이스 간 의존성 제어

__뷰 모델과 뷰의 필요성

__구현 예시

__FastAPI를 사용한 웹 애플리케이션 통합

__컨트롤러와 FastAPI 통합

6.8 정리

 

▣ 07장: 온라인 커피 주문 API 구현

7.1 요구사항 분석

__요구사항 개요

__핵심 유스케이스

__품질 속성

__제약사항

__에러 처리 및 응답 포맷

7.2 연동 규격 정의

__RESTful API 설계 원칙

__API 명세

7.3 디렉터리 구조

__디렉터리 구조의 설계 의도

7.4 CI/CD와 배포

__CI/CD의 중요성

7.5 클린 아키텍처 구현 순서

__1단계: 전체 구조의 뼈대 구현

__2단계: 엔티티 구체화

__3단계: 유스케이스 구체화

__4단계: 저장소 구체화

__5단계: 프레젠터 구체화

7.6 예외 처리

__예외 정의 위치와 의존성

7.7 테스트 전략

__단위 테스트

__API 테스트

7.8 정리

__요구사항 분석과 유스케이스 설계

__클린 아키텍처 기반 코드 작성

__서버리스 배포와 CI/CD

__예외 처리와 테스트 전략

__결론

 

▣ 08장: 클린 아키텍처로 애자일하게 일하기

8.1 워터폴 방법론이란?

8.2 애자일 방법론이란?

__애자일의 핵심 가치와 원칙

__애자일에 대한 오해와 진실

__애자일 실천 방법

8.3 클린 아키텍처와 애자일 방법론

__클린 아키텍처와의 연관성

__클린 아키텍처가 애자일에 기여하는 방식

__클린 아키텍처를 애자일 환경에 적용할 때의 주의 사항

8.4 온라인 커피 주문 API로 본 애자일 적용 사례

8.5 정리

 

▣ 09장: 아키텍처 확장하기

9.1 현대 소프트웨어 아키텍처의 도메인 중심 전환

__기술 중심에서 도메인 중심으로의 패러다임 변화

__도메인 중심 접근이 필요한 현실적 이유

9.2 도메인 주도 설계의 본질

__복잡성을 정복하는 설계 철학

__클린 아키텍처와 DDD의 시너지

__전략적 설계와 전술적 설계

9.3 전략적 설계: 비즈니스의 큰 그림 그리기

__도메인 탐구: 비즈니스의 본질 이해하기

__유비쿼터스 언어: 모두가 이해하는 공통 언어 만들기

__바운디드 컨텍스트: 복잡성을 관리하는 경계

__컨텍스트 맵: 경계 간의 관계 정의

9.4 전술적 설계: 도메인 모델의 구현

__엔티티(Entity): 고유한 정체성을 가진 객체

__값 객체(Value Object): 불변의 개념적 완전성

__애그리게이트(Aggregate): 일관성의 경계와 트랜잭션 단위

__도메인 이벤트(Domain Event): 중요한 비즈니스 사건의 기록

__리포지터리(Repository): 도메인 객체의 영속성 관리

9.5 DDD와 클린 아키텍처의 대응 관계

9.6 클린 아키텍처에서의 MVC 패턴 적용

__MVC 패턴의 구성요소

__MVC 동작 흐름

__MVC에서 클린 아키텍처로 변환하려는 니즈

__클린 아키텍처에서의 MVC 매핑

9.7 클린 아키텍처와 헥사고날 아키텍처의 관계

__헥사고날 아키텍처의 주요 구성요소

__클린 아키텍처와 헥사고날 아키텍처의 구성요소 대응 관계

9.8 마이크로서비스 아키텍처로의 진화

__MSA의 기본 개념과 장점

__DDD와 클린 아키텍처의 시너지: MSA로의 자연스러운 확장

__MSA 도입의 도전 과제와 해결책

9.9 정리

 

▣ 10장: 생성형 AI를 이용한 클린 아키텍처 구현

10.1 AI 시대에 아키텍처 공부가 여전히 필요한 이유

__개발자는 단순히 ‘개발’만 하지 않는다

__약은 약사에게, 진료는 의사에게

__책임과 아키텍처 설계의 인간적 역할

10.2 소프트웨어를 설계하고 구현할 때 생성형

__활용하는 방법

__요구사항 분석 단계: 컨텍스트 구축과 유스케이스 식별

__설계 단계: 아키텍처 원칙 적용과 계층별 구성

__구현과 테스트 단계: 코드 생성과 품질 보장

__배포와 유지보수 단계: 지속적 개선

10.3 사례 연구: AI로 구현한 온라인 커피 주문 API

__프롬프트 엔지니어링

__제로샷 프롬프팅

__원샷 프롬프팅 혹은 퓨샷 프롬프팅

__생각의 사슬 프롬프팅

__프롬프트 복잡성과 실용성의 균형

__AI 생성 코드의 품질 관리를 위한 가드레일 도구와 적용

10.4 AI 기반 아키텍처 확장: 기능 추가와 수정

__DynamoDB에서 RDS(MySQL)로의 전환

__API 및 유스케이스 추가하기

10.5 정리