[PYTHON] 파이썬 프로젝트 계층형 아키텍처(Layered Architecture) 설계 방법 4단계와 복잡성 해결

계층형 아키텍처 (Layered Architecture) 설계

 

파이썬은 유연하고 배우기 쉬운 언어이지만, 프로젝트의 규모가 커질수록 "스파게티 코드"가 되기 쉬운 단점도 가지고 있습니다. 초기에는 빠른 개발 속도를 자랑하던 프로젝트가 어느 순간 수정 하나에 수많은 버그를 양산하게 된다면, 그것은 코드의 품질 문제가 아닌 아키텍처 설계의 부재 때문입니다. 오늘은 파이썬 프로젝트의 유지보수성을 극대화하는 계층형 아키텍처(Layered Architecture) 설계 방법과 그 과정에서 발생하는 의존성 문제를 해결하는 전략을 다루어 보겠습니다.

---

1. 계층형 아키텍처란 무엇인가?

계층형 아키텍처는 소프트웨어를 관심사별로 분리하여 수직적인 층으로 쌓는 구조입니다. 각 계층은 자신의 역할에만 충실하며, 상위 계층은 하위 계층을 사용할 수 있지만 그 반대(하위가 상위를 참조)는 금지됩니다. 이러한 차이가 코드의 결합도를 낮추고 테스트 용이성을 높여줍니다.

2. 파이썬 표준 계층 구성 (4 Layer Model)

파이썬 생태계에 가장 적합한 4단계 계층 설계 방법은 다음과 같습니다.

• Presentation Layer (표현 계층): 사용자 인터페이스를 담당합니다. FastAPI의 엔드포인트나 Flask의 뷰(View)가 여기에 해당합니다.
• Business/Service Layer (비즈니스 계층): 핵심 로직이 위치합니다. 데이터가 어떻게 가공되고 어떤 비즈니스 규칙을 따르는지 결정합니다.
• Persistence Layer (영속성 계층): 데이터베이스와의 통신을 담당합니다. SQLAlchemy 모델이나 리포지토리(Repository) 패턴이 포함됩니다.
• Infrastructure Layer (인프라 계층): 외부 API 호출, 파일 시스템, 메시지 큐 등 외부 시스템과의 연결을 해결합니다.

---

3. 계층형 아키텍처 vs 모놀리식 구조 비교

설계 방식에 따른 명확한 가치 차이를 아래 표를 통해 확인해 보시기 바랍니다.

비교 항목	전통적 모놀리식 (Scripting)	계층형 아키텍처 (Layered)
코드 조직화	기능 중심 (파일 하나에 다수 로직)	역할 중심 (관심사별 폴더 분리)
의존성 방향	복잡하게 얽혀 있음	상위에서 하위로의 단방향 흐름
테스트 용이성	매우 어려움 (DB 연결 필수 등)	매우 쉬움 (Mocking을 통한 독립 테스트)
유지보수 비용	시간이 갈수록 기하급수적 증가	초기 설계 비용은 높으나 장기적 안정
프레임워크 종속성	매우 강함	비즈니스 로직 보호로 종속성 낮음

---

4. [Sample Example] 리포지토리 패턴을 활용한 설계 해결책

파이썬에서 비즈니스 로직과 DB 로직을 분리하여 의존성 문제를 해결하는 구체적인 예시 코드입니다.

# 1. Domain Model (Entity)
class User:
    def __init__(self, id: int, name: str):
        self.id = id
        self.name = name

# 2. Persistence Layer (Repository Interface)
class UserRepository:
    def get_by_id(self, user_id: int) -> User:
        raise NotImplementedError

# 3. Service Layer (Business Logic)
class UserService:
    def __init__(self, repo: UserRepository):
        self.repo = repo  # 의존성 주입(DI)으로 결합도 해결

    def get_user_profile(self, user_id: int):
        user = self.repo.get_by_id(user_id)
        if not user:
            return "User Not Found"
        return f"Hello, {user.name}"

# 4. Presentation Layer (FastAPI Example)
@app.get("/users/{user_id}")
def read_user(user_id: int):
    # 실제 DB 구현체를 주입하여 서비스 호출
    service = UserService(SqlAlchemyUserRepository())
    return service.get_user_profile(user_id)

---

5. 계층형 설계 시 주의해야 할 3가지 원칙

1. 계층 건너뛰기 금지: 표현 계층에서 영속성 계층(DB)으로 직접 접근하는 것은 단기적으로 편하지만, 아키텍처를 파괴하는 지름길입니다. 반드시 서비스 계층을 거쳐야 합니다.
2. 도메인 모델의 순수성 유지: 비즈니스 로직이 담긴 엔티티 객체는 특정 프레임워크(Django, SQLAlchemy 등)의 기능을 직접 상속받지 않도록 설계하는 것이 가장 이상적인 해결 방법입니다.
3. 의존성 주입(DI) 활용: 상위 계층이 하위 계층의 구체적인 클래스를 직접 생성하지 않고, 인터페이스를 통해 주입받음으로써 유연성을 확보해야 합니다.

---

6. 결론: 지속 가능한 성장을 위한 선택

계층형 아키텍처는 단순히 폴더를 나누는 작업이 아닙니다. 이는 변화하는 요구사항 속에서도 코드의 중심(비즈니스 로직)을 지켜내는 방법입니다. 파이썬 프로젝트가 1인 개발을 넘어 팀 단위로 확장될 때, 이러한 아키텍처 설계는 협업의 표준이 되고 코드의 가독성을 비약적으로 향상시키는 최고의 해결책이 될 것입니다.

---

내용 출처 및 기술 참조

• "Architecture Patterns with Python" by Harry Percival & Bob Gregory
• Clean Architecture: A Craftsman's Guide to Software Structure and Design by Robert C. Martin
• Python Dependency Injection Framework (Dependency-injector) Documentation