클린 아키텍처 핵심 가이드

파이썬으로 구현하는 좋은 소프트웨어 설계를 위한 클린 아키텍처

한승희 지음

위키북스 2026년 02월 13일 출간 국내도서 : 2026년 01월 12일 출간

작품소개

책소개

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

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

목차

▣ 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 정리

출판사 서평

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

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

★ 이 책에서 다루는 내용 ★

◎ 좋은 소프트웨어 설계의 본질과 필요성
◎ 설계에 필수적인 소프트웨어 핵심 개념
◎ 클린 아키텍처 이론과 실무 수준의 코드 예제
◎ 실제 애플리케이션 구현 과정을 통해 배우는 설계 원칙 적용 노하우
◎ 도메인 중심 설계 등 현대 소프트웨어 설계 패러다임의 이해
◎ 생성형 AI를 활용한 고품질 소프트웨어 설계 및 개발 기법

인물정보

저자(글) 한승희

연세대학교에서 컴퓨터과학 박사 학위를 취득한 후, 국내 기업 가전 부문에서 IoT 플랫폼 백엔드 개발자로 재직하며 다양한 트러블슈팅 및 소프트웨어 개선 프로젝트를 수행했다. 현재는 통신사에서 소프트웨어 엔지니어 겸 데이터 엔지니어로서 데이터 플랫폼 구축과 소프트웨어 개발 및 유지보수를 담당하고 있다.