클린 아키텍처 with 파이썬: 높은 자유도를 보장하는 파이썬에서 클린 아키텍처는 어떻게 구현할까?

서평단 활동 소개
"한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 책을 협찬 받아 작성된 서평입니다."

클린 아키테겇 with 파이썬

왜 백엔드 개발은 결국 구조의 문제로 돌아오는가

백엔드 개발을 하다 보면 결국 다시 “구조”에 대한 고민으로 돌아오게 되는 것 같습니다. 이 책을 읽은 가장 큰 이유는 회사에서 파이썬 기반으로 구현된 코드가 있는데 아키텍처에 대한 고민이 전혀 없이 구현된 코드를 인계 받았습니다. 그러면서 자연스럽게 파이썬의 자유로움이 나를 구속한다는 것에 큰 좌절을 느끼면서 파이썬 아키텍처를 배워야겠다는 다짐과 함께 도서 리뷰에 당첨되어 읽게 되었습니다. 처음 개발을 시작했을 때는 가장 기본적인 내용부터 습득하는 과정을 거치다 보니까 자연스럽게 문법과 사용 방법에 더 집중하게 됩니다. 어떤 프레임워크를 사용하는지, API를 어떻게 만드는지, 데이터베이스는 어떻게 연결하는지, 요청과 응답은 어떻게 처리하는지 같은 부분들이 우선순위가 됩니다.

 

요구사항을 빠르게 처리하고, API를 만들고, 화면과 연결하고, 장애 없이 운영하는 것만으로도 배울 것이 정말 많았습니다. 실제로 실무 초반에는 “일단 동작하게 만드는 것” 자체가 큰 성장이기도 합니다. 개발 일정은 항상 빠듯하고, 운영 이슈는 계속 발생하고, 새로운 기술은 끊임없이 등장하기 때문에 우선 눈앞의 기능을 완성하는 데 집중할 수밖에 없습니다. 하지만 프로젝트 규모가 커지고 운영 기간이 길어질수록 단순히 “동작하는 코드”만으로는 버티기 어렵다는 것을 점점 체감하게 됩니다. 특히 백엔드 시스템은 시간이 지날수록 복잡도가 빠르게 증가합니다. 처음에는 단순했던 서비스도 다양한 이유로 인해 유지보수가 필요한 경우가 다반사입니다.

 

1. 외부 API 연동 추가

2. 배치 작업이 추가

3. 메시지 큐 기능 확장

4. 인증과 권한 처리가 복잡성 증가

5. 예외 처리 케이스 확장

6. 운영 환경별 분기

7. 장애 대응 로직이 추가

8. 로그 및 모니터링 체계 추가

9. 조건 별 스케줄링 설정

 

위의 예시처럼 대표적인 과정에서 구조가 제대로 잡혀 있지 않으면 코드 수정 하나가 점점 두려워지기 시작합니다. 분명 작은 기능 수정인데도 어디까지 영향이 갈지 예측이 어려워지고, 특정 로직 하나를 변경하기 위해 여러 서비스와 클래스들을 끝없이 따라가야 하는 상황이 발생합니다. 결국 개발 속도는 점점 느려지고, 유지보수 비용은 계속 증가하게 됩니다. 그리고 이 문제는 단순히 “코드를 작성한 개발자 개인의 문제”에서 끝나지 않습니다. 실무에서는 프로젝트에 새로운 인력이 투입되는 경우가 정말 많습니다.

 

1.신규 개발자 합류

2. 신입 개발자가 유지보수 업무를 담당

3. 다른 팀 개발자가 긴급 지원

4. 외주나 협업 인력이 특정 기능을 담당

 

그런데 아무리 실력과 경험이 뛰어난 개발자라고 하더라도, 처음 보는 코드에서 겪는 어려움 자체는 크게 다르지 않습니다. 오히려 복잡한 구조일수록 숙련된 개발자도 더 많은 시간을 분석에 사용하게 됩니다. 특정 기능 하나를 수정하려고 해도 정말 많은 상황을 고려해야만 합니다.

• 실제 비즈니스 로직이 어디에 있는지
• 어떤 계층에서 책임을 가져가는지
• 어떤 외부 시스템과 연결되는지
• 어디까지가 도메인 로직인지
• 어디서 트랜잭션이 시작되는지
• 어떤 API가 어떤 흐름으로 연결되는지

클린 아키텍처: Robert C. Martin

 

마틴 파울러와 함께 애자일 진영을 이끈 로버트 C. 마틴이 저서 《클린 코드(Clean Code)》에서 정확히 이 비율과 시니어 개발자의 현실을 짚었습니다.

"새 코드를 짜는 시간과 기존 코드를 읽는 시간의 비율은 1 대 10을 넘는다. 우리는 새 코드를 짜기 위해 끊임없이 기존 코드를 읽는다. [...] 그러므로 읽기 쉬운 코드를 짜는 것은 결국 짜는 속도도 빨라지게 만든다."

로버트 C. 마틴조차 아무리 숙련된 개발자(시니어)라 할지라도 전체 업무 시간의 90% 이상을 코드를 읽고 분석하는 데 쓰기 때문에, 코드가 나쁘면 시니어고 뭐고 진도를 나갈 수 없다고 강조했습니다. 이처럼 아무리 훌륭하게 작성된 코드이더라도, 복잡성과 코드의 양이 높아질수록 파악하는 데 실력과 무관하게 누구나 상당한 시간이 들어갑니다. 특히 구조가 무너진 프로젝트에서는 “이 클래스가 왜 존재하는지” 자체를 이해하기 어려운 경우도 많습니다. 공감되는 아래 예시들은 다음과 같습니다.

• Controller에서 비즈니스 로직을 처리
• Service가 지나치게 비대
• Repository에서 도메인 로직까지 수행
• 특정 외부 API 로직이 여러 계층에 흩어진 상황
• 공통 로직이 중복되어 퍼져 있는 경우

처음 프로젝트에 투입된 개발자는 기능 구현보다 “코드 탐색”에 더 많은 시간을 쓰게 됩니다. 결국 좋은 구조라는 것은 단순히 “코드를 예쁘게 만드는 것”이 아니라, 다른 사람이 이해할 수 있는 형태로 시스템을 조직하는 것에 더 가깝다고 생각합니다. 그리고 그 과정에서 형상관리와 문서화의 중요성도 굉장히 커집니다. 아키텍처가 아무리 잘 되어 있어도 합리적인 이유와 명확한 의도가 포함되어야만 합니다.

• 왜 이런 구조를 선택했는지
• 어떤 의도로 계층을 나눴는지
• 어떤 규칙을 지켜야 하는지
• 외부 시스템 의존성은 어디에 있는지

같은 정보가 남아 있지 않으면 시간이 지나면서 결국 구조는 무너지게 됩니다. 특히 운영 기간이 긴 프로젝트일수록 코드보다 문맥(Context)이 더 중요해지는 순간이 많습니다. “왜 이렇게 구현했는가?”에 대한 정보가 사라지면 이후 개발자는 결국 추측 기반으로 수정하게 됩니다. 그리고 이런 상황이 반복되면 점점 구조 일관성이 깨지고, 기술 부채는 빠르게 쌓이게 됩니다. 그래서 저는 좋은 아키텍처는 단순히 계층을 나누는 기술적인 개념만이 아니라 전사적인 관점에서 바라보고 있습니다.

• 코드 구조
• 형상관리 전략
• 문서화 방식
• 팀 내 규칙
• 책임 분리
• 변경 이력 관리

을 기본적으로 포함하는 “협업 가능한 시스템 설계”에 더 가깝다고 생각하게 되었습니다. 위 항목과 동일한 수준으로 중요한 것은 도메인에 대한 이해인데, 이것은 코드 내용과 별개이기 때문에 넘어가겠습니다. 저는 공부한 내용의 대부분이 스프링부트 기반 백엔드 개발입니다. 그러다 보니 자연스럽게 계층형 아키텍처(Layered Architecture), 헥사고날 아키텍처(Hexagonal Architecture), 그리고 클린 아키텍처(Clean Architecture)에 익숙한 환경에서 개발해왔습니다. 스프링은 사실상 프레임워크 자체가 어느 정도 구조를 유도합니다.

• Controller
• Service
• Repository
• DTO
• Entity

https://static.packt-cdn.com/downloads/9781836642893_ColorImages.pdf

같은 계층 구분이 매우 자연스럽고, DI(Dependency Injection) 기반 구조도 기본적으로 제공됩니다.
조금 더 발전하면 다음과 같습니다.

• UseCase
• Port & Adapter
• Domain Layer
• Application Layer

같은 형태로 확장하는 것도 비교적 익숙합니다. 그래서 저는 평소에도 “비즈니스 로직을 어디까지 분리할 것인가”, “외부 의존성을 어떻게 격리할 것인가”, “테스트 가능한 구조를 어떻게 만들 것인가” 같은 고민을 자주 하는 편이었습니다. 코드 수준에서 아키텍처 설계 뿐만 아니라 인프라 아키텍처 설계 또한 상당히 중요하게 생각하고 있습니다. 

내가 이전에 설계한 모니터링 서비스 아키텍처

 

좋은 백엔드 설계의 본질은 언어가 아니라 구조

반면 파이썬은 제게 조금 다른 이미지였습니다. 물론 간단한 자동화나 스크립트 작성에서는 굉장히 강력한 언어라고 생각했습니다. 하지만 대규모 백엔드 시스템 관점에서는 솔직히 약간의 거리감이 있었습니다. 특히 가장 먼저 거부감이 들었던 부분은 프로젝트 구조였습니다. 패키지를 구성할 때마다 등장하는 `__init__.py` 파일도 그렇고, 스프링처럼 강한 타입 기반 구조가 아니다 보니 코드가 쉽게 흩어질 수 있다는 느낌이 강했습니다. 스프링부트에서는 어느 정도 “정리된 형태”가 기본 전제로 깔려 있습니다. 반면 파이썬은 개발자가 의도적으로 구조를 만들지 않으면 구조는 언제든지 무너지기 쉬운 환경이라고 생각이 들었습니다.

• 기능 중심 스크립트
• 순환 참조
• 모듈 간 강한 결합
• 서비스 객체 비대화

그리고 바로 이 지점에서 이 책에 대한 흥미가 생기기 시작했습니다. 처음에는 단순히 “파이썬으로 클린 아키텍처를 설명하는 책” 정도로 생각했습니다. 하지만 실제로 읽어보니 단순한 파이썬 문법 중심의 책이 아니라, 유지보수 가능한 시스템을 어떻게 설계할 것인가에 대한 고민이 훨씬 깊게 담겨 있었습니다. 특히 좋았던 부분은 단순히 이론만 설명하지 않는다는 점입니다.

• SOLID 원칙
• 타입 시스템
• 도메인 주도 설계(DDD)
• 유스케이스 기반 설계
• 인터페이스 어댑터
• 외부 시스템 의존성 분리
• 테스트 전략
• 관측 가능성(Observability)
• 레거시 리팩터링

내용으로 이어지는데, 단순히 “이렇게 하는 것이 좋다” 수준이 아니라 실제 프로젝트에서 왜 이런 구조가 필요한지를 계속 설명합니다. 특히 스프링부트 개발자인 제 입장에서는 익숙한 개념들이 굉장히 많이 등장했습니다. 예를 들어 책에서 계속 강조하는 핵심 흐름은 결국 다음과 같습니다.

• 도메인은 외부 기술을 몰라야 한다.
• 비즈니스 로직은 프레임워크에 종속되면 안 된다.
• 외부 API, DB, 메시지큐 같은 요소는 교체 가능해야 한다.
• 핵심 로직은 테스트 가능해야 한다.
• 의존성 방향은 항상 내부를 향해야 한다.

사실 이 내용들은 스프링 진영에서도 계속 중요하게 이야기되는 부분입니다. 대표적으로 헥사고날 아키텍처(Hexagonal Architecture)나 Port & Adapter 패턴 역시 외부 시스템 격리, 의존성 역전, 도메인 보호, 테스트 용이성 확보를 목표로 합니다.

그래서 책을 읽으면서 단순히 “파이썬스럽다”라는 느낌보다, 오히려 “좋은 백엔드 설계의 본질은 언어와 크게 상관없구나”라는 생각이 더 강하게 들었습니다. 다만 흥미로웠던 점은, 스프링과 파이썬의 차이에서 오는 설계 체감이었습니다. 스프링은 프레임워크가 굉장히 많은 것을 제공해줍니다. 예를 들어, DI 컨테이너, Bean 생명주기, AOP, 트랜잭션 관리, Validation, Repository 추상화, MVC 패턴, 테스트 지원 등과 같은 기능들이 기본적으로 제공되기 때문에, 어느 정도 “권장되는 구조” 안에서 개발하게 됩니다. 반면 파이썬은 훨씬 자유롭습니다. 이 자유로움은 장점이기도 하지만, 동시에 굉장히 위험하기도 합니다. 구조에 대한 기준이 없으면, util.py 하나에 모든 기능이 몰리거나, 특정 서비스 객체가 비정상적으로 비대해지거나, DB 접근 로직과 비즈니스 로직이 섞이거나, 외부 API 호출 코드가 여기저기 퍼지거나, 순환 참조 문제가 발생하거나, 테스트 자체가 어려운 구조로 빠르게 변질될 수 있습니다. 그리고 이 책은 바로 그런 문제를 해결하기 위한 “구조적 기준”을 제시합니다. 특히 인상 깊었던 부분은 파이썬에서도 충분히 강한 경계(boundary)를 만들 수 있다는 점이었습니다.

 

처음에는 동적 타입 언어 특성상, "인터페이스 분리가 애매하지 않을까?, 의존성 관리가 어렵지 않을까?, 구조가 쉽게 무너지지 않을까?" 라는 생각이 있었는데, 책에서는 Python의 typing 시스템과 Protocol, 추상 클래스(Abstract Base Class) 등을 활용해 충분히 안정적인 설계를 구성하는 방법을 설명합니다. 이 부분은 생각보다 굉장히 흥미로웠습니다. 왜냐하면 최근 자바 진영 역시 예전보다 훨씬 유연한 방향으로 변하고 있기 때문입니다.

 

결국 중요한 것은 언어 문법 자체보다 “어떻게 책임과 경계를 나누느냐”라는 점이라는 생각이 들었습니다. 또 하나 인상 깊었던 부분은 테스트 전략입니다. 실무에서 가장 어려운 것 중 하나가 “운영 가능한 테스트 구조”를 유지하는 것이라고 생각합니다. 특히 스프링부트 프로젝트는 규모가 커질수록 테스트도 무거워지는 경우가 많습니다. 처음에는 단순한 단위 테스트로 시작하지만, DB 연결, Redis 연결, Kafka 연결, 외부 API Mock, Security Context, JPA Entity, 트랜잭션 처리 등이 얽히면서 테스트 자체가 복잡해집니다. 그리고 어느 순간부터는 `@SpringBootTest` 하나로 모든 것을 검증하려는 방향으로 흐르기도 합니다. 물론 통합 테스트는 중요합니다. 하지만 모든 테스트가 통합 테스트 수준으로 무거워지면 실행 속도가 느려지고, 유지보수 비용이 증가하고, 테스트 실패 원인 분석이 어려워지고, 개발자가 테스트 자체를 부담스럽게 느끼게 됩니다.

 

이 책은 그런 문제를 “구조 분리” 관점에서 접근합니다.
핵심 비즈니스 로직을 외부 의존성으로부터 분리를 어떻게 해야 좋을지 제안합니다.

• 테스트 범위를 줄일 수 있고
• Mocking 범위를 최소화할 수 있으며
• 빠른 피드백이 가능하고
• 유스케이스 단위 검증이 쉬워진다는 점을 계속 강조합니다.

이 부분은 현재 운영 중인 백엔드 시스템들을 떠올리면서 더욱 공감되었습니다.

• 외부 SIEM 연동
• 모니터링 시스템 연동
• 스케줄링 배치
• PDF 생성
• 메시지 큐 기반 비동기 처리
• 장애 복구 로직

같은 요소들이 계속 추가될수록, 비즈니스 로직과 인프라 로직을 분리하는 것이 얼마나 중요한지 점점 크게 느끼게 됩니다. 결국 시간이 지나도 유지보수 가능한 시스템은 “좋은 기술을 사용한 시스템”이 아니라, 변경 가능한 구조를 가진 시스템이라는 생각이 들었습니다.

Chapter 10 관측 가능성 구현: 모니터링과 검증

 

마지막으로 이 책이 좋았던 이유는 단순히 “클린 아키텍처를 구현하는 방법”만 설명하지 않는다는 점입니다. 많은 아키텍처 관련 책들이 이상적인 구조와 설계 원칙을 설명하는 데 집중하는 반면, 이 책은 실제로 운영되는 시스템이 시간이 지나면서 어떤 문제를 겪게 되는지까지 함께 이야기합니다.

• 테스트 가능한 구조
• 외부 의존성 분리
• 관측 가능성(Observability)
• 모니터링 전략
• 레거시 시스템 리팩터링
• 점진적인 아키텍처 전환

같은 내용들을 함께 다룬다는 점이 굉장히 실무적으로 느껴졌습니다. 실제 현업에서는 처음부터 완벽한 구조로 시작하는 경우보다, 이미 운영 중인 시스템을 유지·보수하면서 점진적으로 개선해야 하는 경우가 훨씬 많기 때문입니다. 특히 레거시 환경에서는 비즈니스 로직과 인프라 로직이 섞여 있거나, 특정 프레임워크 의존성이 지나치게 강하거나, 테스트 자체가 어려운 구조이거나, 변경 영향 범위를 예측하기 어려운 경우가 굉장히 흔합니다. 그런 상황에서 이 책은 단순히 “이렇게 구현하세요”라고 끝나는 것이 아니라, 왜 이런 구조가 필요한지, 어떤 기준으로 경계를 나눠야 하는지, 어떻게 점진적으로 개선해야 하는지, 운영 가능한 테스트 구조를 어떻게 유지해야 하는지를 계속 설명합니다.

 

개인적으로는 이 부분이 단순한 아키텍처 입문서와 가장 크게 달랐던 지점이라고 생각합니다. 결국 파이썬이라는 언어는 굉장히 자유롭습니다. 그리고 그 자유로움은 생산성을 높여주기도 하지만, 동시에 구조를 쉽게 무너뜨릴 수도 있습니다. 이 책은 바로 그 지점에서 “파이썬다운 유연함 속에서도 어떻게 아키텍처의 철학을 유지할 것인가” 에 대한 방향성을 제시해주는 책이라고 느껴졌습니다. 단순히 디자인 패턴을 나열하거나 이론적인 구조를 설명하는 것이 아니라, 실제 프로젝트에서 유지보수 가능한 구조를 어떻게 만들어야 하는지에 대한 가이드에 더 가까웠습니다. 파이썬으로 개발하는 모든 분들이라면 반드시 한 번은 부딪히게 될 아키텍처 공부는 필수적이라고 생각합니다. 그래서 다음과 같은 분들에게 추천드립니다.

• 파이썬을 주력 언어로 사용하는 개발자
• 레거시 프로젝트 리팩터링을 고민하는 개발자
• 클린 아키텍처를 실무 관점에서 이해하고 싶은 개발자

위에 해당되는 분들에게 상당히 추천할 만한 책이라고 생각합니다. 저 역시 처음에는 단순히 “파이썬 기반 클린 아키텍처 책” 정도로 접근했지만, 읽고 나서는 언어를 넘어 “좋은 소프트웨어 구조란 무엇인가”를 다시 고민하게 만든 책으로 기억에 남았습니다. 

 

https://netflixtechblog.com/

 

다만 이 책을 읽으면서도 한 가지 생각은 분명했습니다. 파이썬은 빠른 개발과 높은 자유도를 제공하는 언어이지만, 아키텍처를 강하게 고려해야 할 정도로 복잡한 대규모 백엔드 시스템이라면 여전히 스프링부트가 더 안정적인 선택일 수 있겠다는 점입니다. 스프링부트는 DI, 트랜잭션 관리, Validation, AOP, 테스트 지원 등 엔터프라이즈 애플리케이션에 필요한 기반을 프레임워크 차원에서 제공하고, 자연스럽게 계층 구조를 유도합니다. 반면 파이썬은 자유로운 만큼 구조를 유지하기 위해 개발자와 팀의 규율이 더 많이 요구됩니다. 결국 파이썬이 부족하다는 의미라기보다는, 언어와 프레임워크의 강점이 다르다는 뜻에 가깝습니다. 빠른 실험과 유연한 구현이 중요한 영역에서는 파이썬이 강력하지만, 복잡한 도메인과 장기 유지보수가 중요한 엔터프라이즈 백엔드에서는 스프링부트가 더 적합한 선택이 될 수 있다고 생각합니다.

공부에 도움이 되는 자료들

GitHub - PacktPublishing/Clean-Architecture-with-Python: Clean Architecture with Python, Published by Packt

GitHub - songys/Clean-Architecture-with-Python