REAL PROJECT 03 · DJANGO LAYERED ARCHITECTURE

백엔드 프레임워크 기본 구조를 넘어,레이어드 아키텍처를 설계하다 ( Django 예시 )

API·비즈니스 로직·데이터베이스·외부 결제 API를 책임별 계층으로 분리하고, 여러 개발자와 AI 개발 에이전트가 충돌 없이 일관된 위치에 코드를 작성할 수 있는 실무형 백엔드 아키텍처와 개발 규격을 완성합니다.

dependency-flow.py (클릭하여 슬라이드 열기)
apps / API (View · Serializer) HTTP 요청 검증 · Workflow 호출
↓ calls
business / Workflow 유스케이스 전체 처리 순서 조율
↓ orchestrates
business / Rule · Policy · Calculator 순수 업무 규칙 · 정책 결정 · 금액 계산 (Django 비의존)
↓ depends on interface ↑ implements
business / Port (Protocol) OrderRepository · PaymentGateway 인터페이스
↑ implements
infrastructure / Repository · Adapter Django ORM · Toss 결제 API · Outbox 구현체
20 Chapters이론부터 결제·AI 규격까지 완주
5대 핵심 계층config · apps · business · infra · tests
2대 실전 도메인카페 주문 API + 빌링·결제 모듈
12-Step AI 규격AI 에이전트 일관성 보장 표준
INTERACTIVE 20-SLIDE DECK · CLICK TO OPEN 카드를 클릭하면 해당 챕터 슬라이드가 즉시 열립니다
CHAPTER 01 – 03 · OVERVIEW & PROBLEM STATEMENT

1. 강의 개요 및 왜 레이어드 아키텍처가 필요한가?

Django의 빠른 생산성을 유지하면서 서비스 규모 확장에 따른 Fat View·중복 규칙·테스트 불가·AI 코드 파편화 문제를 해결합니다.

01 강의 주제: 6대 핵심 설계 요구사항

Django의 기본 구조를 확장하여 다음 요구사항을 만족하는 레이어드 아키텍처를 설계합니다.

  • API와 비즈니스 로직 분리 — View가 모든 일을 처리하지 않도록 분리
  • 데이터베이스 접근 로직 분리 — ORM 쿼리를 Repository 뒤에 캡슐화
  • 자주 변경되는 업무 규칙의 라이브러리화 — Rule·Policy·Calculator 모듈화
  • 여러 개발자가 동시에 작업하기 쉬운 구조 — 파일 단위 책임 분리로 Git 충돌 최소화
  • 외부 결제 API와 서드파티 연동 구조화 — Port & Adapter 기반 느슨한 결합
  • AI 개발 에이전트가 일관되게 코드를 작성할 수 있는 개발 규격 수립

02 7대 학습 목표

수강생은 강의가 끝난 후 다음 내용을 설명하고 직접 구현할 수 있어야 합니다.

  • 1. Django 기본 구조(models.py, views.py 비대화)의 한계를 이해한다.
  • 2. Model, API, Business, Infrastructure 계층을 구분한다.
  • 3. Rule, Policy, Calculator, Workflow의 역할을 구분한다.
  • 4. Repository와 Port를 이용해 DB와 외부 시스템 의존성을 분리한다.
  • 5. 카페 주문 API를 레이어드 아키텍처로 구현한다.
  • 6. 외부 결제사를 Adapter 형태로 추가한다.
  • 7. AI가 따라야 할 프로젝트 개발 규격을 작성한다.

⚠️ 안티패턴: 하나의 View가 너무 많은 일을 처리하는 코드 (Ch 02)

HTTP 요청 처리, DB 조회, 판매 가능 판단, 금액 계산, 주문 저장, 외부 결제 호출이 한 View에 뒤섞인 구조입니다.

class OrderCreateView(APIView): def post(self, request): menu = Menu.objects.get(id=request.data["menu_id"]) if not menu.is_available: raise ValidationError("판매 중인 메뉴가 아닙니다.") total_price = menu.price * request.data["quantity"] order = Order.objects.create( user=request.user, total_price=total_price, ) PaymentAPI.confirm(...) return Response({"order_id": order.id})
  • 같은 업무 규칙이 여러 API에 중복된다.
  • 비즈니스 로직을 DB 없이 단위 테스트하기 어렵다.
  • 여러 개발자가 같은 파일을 동시에 수정하며 충돌한다.
  • 외부 API 변경이 전체 서비스에 영향을 준다.
  • AI가 코드를 작성할 위치를 일관되게 판단하기 어렵다.

📁 Django 기본 구조와 파일 비대화 문제 (Ch 03)

작은 프로젝트에서는 충분하지만 기능이 커지면 models.py, views.py, serializers.py, tests.py가 수천 줄로 비대해집니다.

backend/ ├── manage.py ├── config/ │ ├── settings.py │ ├── urls.py │ ├── asgi.py │ └── wsgi.py └── cafe/ ├── migrations/ ├── admin.py ├── apps.py ├── models.py # ⚠️ 수천 줄로 비대화 ├── serializers.py # ⚠️ 검증 + 비즈니스 혼재 ├── tests.py # ⚠️ 느린 DB 의존 테스트 └── views.py # ⚠️ HTTP + 쿼리 + 결제 혼재

💡 해결책: Django 앱 내부 파일을 책임에 따라 나누고, 순수 business 계층과 infrastructure 계층을 추가합니다.

CHAPTER 04 – 05 · TARGET ARCHITECTURE & DEPENDENCY RULE

2. 목표 아키텍처와 단방향 의존성 원칙

5대 최상위 디렉터리로 책임을 분리하고, Business 계층이 Django ORM이나 외부 API에 직접 의존하지 않도록 Port 인터페이스를 경계로 세웁니다.

🏗️ 4.1 목표 아키텍처 전체 디렉터리 구조

backend/ ├── manage.py ├── pyproject.toml ├── config/ # Django 전역 설정 ├── apps/ # Django와 HTTP 계층 │ ├── cafe/ │ └── billing/ ├── business/ # 순수 비즈니스 로직 (Django import 금지) │ ├── core/ │ ├── cafe/ │ └── billing/ ├── infrastructure/ # DB 및 외부 시스템 구현 (Port 구현체) │ ├── repositories/ │ ├── transactions/ │ ├── payment_gateways/ │ ├── notifications/ │ └── outbox/ └── tests/ # 3단계 테스트 스위트 ├── unit/ ├── integration/ └── contract/

📋 4.2 계층별 핵심 책임

계층책임
configDjango 프로젝트 전체 설정 (settings, urls, wsgi/asgi)
appsHTTP 요청/응답(DRF API), Django Model 정의, 관리자(Admin) 및 container.py
business순수 업무 규칙(Rule), 정책(Policy), 계산(Calculator), 처리 절차(Workflow), 인터페이스(Port)
infrastructureDjango ORM Repository, 트랜잭션(UoW), 외부 결제 API Adapter, 메시지/이메일, Outbox
tests단위(Unit, DB 무관) · 통합(Integration, DB/ORM) · 계약(Contract, 외부 Adapter) 테스트
🧭 5. 핵심 의존성 원칙

API → Workflow → Rule·Policy·Calculator → Port ← Infrastructure Adapter → DB / External API.
Business 계층은 Django와 DRF를 절대 import하지 않습니다.

🚫 금지되는 의존성 (Business에서 ORM 직접 호출)

# ❌ business 계층에서 절대 금지! from django.db import transaction from apps.cafe.models import Order Order.objects.create(...)

✅ 허용되는 의존성 (Port 인터페이스 주입)

# ✅ Workflow는 어떤 DB를 사용하는지 알지 못한다 class CreateOrderWorkflow: def __init__(self, order_repository: OrderRepository): self.order_repository = order_repository
CHAPTER 06 · PURE BUSINESS LAYER COMPONENTS

3. Business 계층의 6대 구성요소

business/cafe/ 내부는 dto, rules, policies, calculators, workflows, ports로 세분화되어 각자의 단일 책임을 수행합니다.

6.1 DTO (Data Transfer Object)

계층 사이에서 데이터를 전달하는 불변 객체입니다. DTO에는 Django Model을 사용하지 않습니다.

from dataclasses import dataclass @dataclass(frozen=True) class OrderItemCommand: menu_id: int quantity: int @dataclass(frozen=True) class CreateOrderCommand: customer_id: int items: tuple[OrderItemCommand, ...]

6.2 Rule (단일 조건 판단)

하나의 업무 조건만 판단합니다 (예: 주문 수량, 판매 중 여부, 주문 가능 시간, 할인 대상 여부).

class OrderQuantityRule: def evaluate(self, quantity: int) -> RuleResult: if quantity < 1: return RuleResult.reject( code="INVALID_QUANTITY", message="주문 수량은 1개 이상이어야 합니다.", ) return RuleResult.accept()

6.3 Policy (복합 규칙 결정)

여러 Rule을 조합해 최종 결정을 내립니다 (예: 주문 접수 정책, 취소 정책, 할인 정책, 환불 정책).

class OrderAcceptancePolicy: def __init__(self, rules): self.rules = rules def evaluate(self, context): for rule in self.rules: result = rule.evaluate(context) if not result.passed: return result return RuleResult.accept()

6.4 Calculator (순수 계산기)

같은 입력에 항상 같은 결과를 반환하며, DB/외부 API를 호출하지 않고 금액 계산에 float를 쓰지 않습니다.

class OrderPriceCalculator: def calculate(self, items): return sum( item.unit_price * item.quantity for item in items )

6.5 Workflow (유스케이스 절차 조율)

하나의 유스케이스에 필요한 전체 처리 순서를 관리하며, 직접 계산·판단하기보다 Rule, Policy, Calculator를 조합합니다.

class CreateOrderWorkflow: def __init__( self, menu_repository, order_repository, acceptance_policy, price_calculator, unit_of_work, ): self.menu_repository = menu_repository self.order_repository = order_repository self.acceptance_policy = acceptance_policy self.price_calculator = price_calculator self.unit_of_work = unit_of_work def execute(self, command): menus = self.menu_repository.get_available_menus( menu_ids=[item.menu_id for item in command.items] ) self.acceptance_policy.validate(menus=menus, items=command.items) total_price = self.price_calculator.calculate(items=command.items, menus=menus) with self.unit_of_work: return self.order_repository.create_order( customer_id=command.customer_id, items=command.items, total_price=total_price, )

6.6 Port (외부 기능 인터페이스)

Business 계층이 외부 계층에 요구하는 기능의 Protocol 인터페이스입니다. 실제 구현은 infrastructure에 둡니다.

from typing import Protocol class OrderRepository(Protocol): def create_order(self, order_data): ... def get_order(self, order_id: int): ...
CHAPTER 07 – 08 · CAFE ORDER API & DEPENDENCY INJECTION

4. 실전 적용 사례 1: 카페 주문 API & 의존성 조립

7단계 주문 요구사항을 폴더 구조와 파이프라인으로 매핑하고, container.py에서 구현체를 주입(DI)합니다.

☕ 7.1 요구사항 & 7.3 처리 흐름

  1. 요청 데이터 검증 (CreateOrderSerializer)
  2. CreateOrderCommand DTO 생성
  3. 메뉴 조회 (MenuRepository)
  4. 판매 가능 여부 + 수량 검증 (OrderAcceptancePolicy)
  5. 총금액 계산 (OrderPriceCalculator)
  6. 주문·항목 트랜잭션 저장 (OrderRepository)
  7. 주문 결과 반환 (201 Created)
// POST /api/v1/cafe/orders 요청 { "items": [ { "menu_id": 1, "quantity": 2 }, { "menu_id": 3, "quantity": 1 } ] } // 응답 { "order_id": 1042, "status": "RECEIVED", "total_price": 13500 }

📂 7.2 카페 도메인 폴더 구조

apps/cafe/ ├── models/ (menu.py, order.py, order_item.py) ├── api/ (serializers.py, views.py, urls.py) └── container.py business/cafe/ ├── dto/ (order_command.py, order_result.py) ├── rules/ (menu_available_rule.py, order_quantity_rule.py) ├── policies/ (order_acceptance_policy.py) ├── calculators/ (order_price_calculator.py) ├── workflows/ (create_order_workflow.py) └── ports/ (menu_repository.py, order_repository.py, unit_of_work.py) infrastructure/ ├── repositories/ (django_menu_repository.py, django_order_repository.py) └── transactions/ (django_unit_of_work.py)

🧩 8. 의존성 조립 (container.py)

Workflow 내부에서 DjangoOrderRepository()를 직접 생성하지 않고 container.py에서 조립합니다.

# apps/cafe/container.py def create_order_workflow() -> CreateOrderWorkflow: return CreateOrderWorkflow( menu_repository=DjangoMenuRepository(), order_repository=DjangoOrderRepository(), acceptance_policy=OrderAcceptancePolicy(...), price_calculator=OrderPriceCalculator(), unit_of_work=DjangoUnitOfWork(), )
  • 단위 테스트에서 FakeRepository 즉시 주입 가능
  • DB 및 외부 API 구현체 교체 용이
  • Workflow가 기술 세부사항에 종속되지 않음
CHAPTER 09 – 16 · BILLING, PORT & ADAPTER, IDEMPOTENCY, WEBHOOK & OUTBOX

5. 실전 적용 사례 2: 빌링·결제 모듈 아키텍처 확장

외부 결제사 연동, 네트워크 Timeout, 중복 승인 방지(Idempotency), 웹훅 검증, Outbox 이벤트 발행을 Port & Adapter 패턴으로 격리합니다.

🔌 10. PaymentGateway Port & Toss Adapter

Business 계층은 Toss라는 이름이나 응답 형식을 전혀 알지 못하며 오직 PaymentGateway Protocol만 바라봅니다.

class PaymentGateway(Protocol): provider_code: str def confirm(self, command) -> PaymentResult: ... def get_payment(self, provider_payment_id) -> PaymentResult: ... def cancel(self, command) -> RefundResult: ... def verify_webhook(self, raw_body, headers) -> bool: ... class TossPaymentGateway: provider_code = "TOSS" def __init__(self, client, mapper): self.client = client self.mapper = mapper def confirm(self, command): response = self.client.confirm_payment( payment_key=command.payment_key, order_id=command.order_id, amount=command.amount, ) return self.mapper.to_payment_result(response)

📌 Adapter 내부 6대 파일: adapter.py · client.py · mapper.py · schemas.py · signature.py · exceptions.py

🗂️ 11. 결제사 Registry & 12. 상태 전이 머신

if provider == "TOSS": 분기문 대신 PaymentGatewayRegistry로 결제사를 선택하여, 신규 결제사 추가 시 기존 Workflow 수정이 0줄입니다.

class PaymentGatewayRegistry: def __init__(self, gateways): self._gateways = {g.provider_code: g for g in gateways} def get(self, provider_code): return self._gateways[provider_code]
✅ 허용 상태 전이: READY → PENDING → PAID / FAILED, PAID → PARTIAL_REFUND → REFUNDED, PAID → CANCELLED
🚫 금지 상태 전이: FAILED → REFUNDED, READY → CANCELLED, REFUNDED → PAID

⚡ 13. 승인 트랜잭션 분리

외부 API 호출 중에는 DB 트랜잭션을 물고 있지 않습니다.

  • 짧은 TX 1: PENDING 변경
  • TX 외부: 결제사 승인 API 호출
  • 짧은 TX 2: 결제 결과 + Outbox 저장
  • Timeout 시 즉시 실패 확정 금지 (조회/웹훅 확인)

🛡️ 14. 멱등성 (Idempotency)

네트워크 재전송으로 인한 중복 결제를 원천 차단합니다.

  • Idempotency-Key 헤더 필수
  • 동일 Key + 동일 요청 → 기존 결과 반환
  • 동일 Key + 다른 금액 → 409 Conflict
  • provider_payment_id Unique 제약

🔔 15. 웹훅(Webhook) 원칙

중복 수신과 이벤트 순서 역전에 안전해야 합니다.

  • Raw Body로 서명(Signature) 검증
  • 외부 event_id Unique 제약
  • 과거 이벤트가 최신 상태를 덮어쓰지 못하게 방어
  • 실패 이벤트 재처리 가능 구조

📦 16. Outbox 패턴

후속 작업 장애가 결제 승인을 롤백시키지 않도록 분리합니다.

  • Payment 저장과 PAYMENT_COMPLETED Outbox 이벤트를 동일 TX에 저장
  • Commit 후 Outbox Publisher가 주문 상태 변경·영수증·알림 비동기 발행
CHAPTER 17 – 20 · TEST STRATEGY, AI SPEC & FILE PLACEMENT

6. 3단계 테스트 전략 · AI 개발 규격 · 파일 배치 판단법

AI 에이전트가 어디에 어떤 코드를 작성하고 어떻게 검증해야 하는지 명확한 규칙과 매트릭스로 정의합니다.

🧪 17.1 단위 테스트 (Unit)

tests/unit/business/ — DB 없이 순수 Business 계층을 밀리초 단위로 검증합니다.

  • 주문 수량·판매 가능 여부·총액 계산
  • 결제 상태 전이·부분 환불 한도
  • 중복 결제·Timeout·역순 웹훅 처리

🔗 17.2 통합 테스트 (Integration)

tests/integration/ — 실제 Django 모델, 트랜잭션, DB 제약조건을 검증합니다.

  • 주문 + 주문 항목 원자적 저장 및 Rollback
  • 결제 + 결제 시도 이력 + Outbox 동시 저장
  • 웹훅 중복 이벤트 1회 처리 보장

📜 17.3 Adapter 계약 테스트 (Contract)

tests/contract/payment_gateways/ — 모든 결제사 Adapter가 동일한 규격을 지키는지 검증합니다.

  • 승인 성공/거절 DTO 변환 일관성
  • Timeout·알 수 없는 응답 예외 분류
  • 웹훅 서명 검증 및 상태 매핑

🤖 18. AI 개발 에이전트 12단계 구현 순서

  1. 기존 프로젝트 규격을 읽는다.
  2. 관련 도메인의 기존 코드를 검색한다.
  3. DTO와 오류 코드를 정의한다.
  4. Rule, Policy, Calculator를 구현한다.
  5. 단위 테스트(Unit Test)를 작성한다.
  6. Port 인터페이스를 정의한다.
  7. Workflow를 구현한다.
  8. Django Model과 Migration을 작성한다.
  9. Repository 또는 Adapter를 구현한다.
  10. API (Serializer · View · URL)를 구현한다.
  11. container.py에서 의존성을 조립한다.
  12. 전체 테스트와 정적 검사를 실행한다.

⛔ 18. AI가 절대 하지 않아야 하는 9대 금지 작업

  • View에 복잡한 비즈니스 로직 작성
  • Business 계층에서 Django ORM 직접 사용
  • 기존 공통 Rule을 확인하지 않고 코드 복제
  • 결제사 원본 응답을 API에 그대로 반환
  • 실패 테스트 없이 임시 조건문으로 버그 수정
  • 기존 Migration 파일 임의 변경
  • 결제 Secret Key를 코드에 하드코딩
  • 요청받지 않은 대규모 리팩터링 수행
  • 실행하지 않은 테스트를 통과했다고 거짓 보고

🧭 19. 파일 배치 판단법 매트릭스

질문: “이 코드는 Django와 DB가 없어도 실행할 수 있는 업무 규칙인가?” → Yes면 무조건 business/!

코드 종류작성 위치
DB 테이블 정의apps/<domain>/models
요청·응답 검증 (HTTP)apps/<domain>/api
단일 업무 조건business/<domain>/rules
여러 조건의 조합business/<domain>/policies
금액·점수·기간 계산business/<domain>/calculators
업무 처리 절차business/<domain>/workflows
외부 기능 인터페이스business/<domain>/ports
Django ORM 구현infrastructure/repositories
특정 결제사 구현infrastructure/payment_gateways
의존성 조립apps/<domain>/container.py

🎯 20. 강의 핵심 정리: 변경의 영향을 가두는 구조

레이어드 아키텍처의 목적은 폴더를 많이 만드는 것이 아니라, 변경의 영향을 특정 영역에 제한하는 것입니다.

API 스펙 변경 → apps/api만 변경 업무 규칙 변경 → business/rules 또는 policies만 변경 금액 계산 공식 변경 → business/calculators만 변경 DB 접근 방식 변경 → infrastructure/repositories만 변경 외부 결제사 추가/변경 → infrastructure/payment_gateways adapter만 변경

🔥 반드시 기억할 5대 핵심 원칙

  • 1. View는 요청을 받고 Workflow를 호출한다.
  • 2. Workflow는 업무 처리 순서를 관리한다.
  • 3. Rule, Policy, Calculator는 순수 비즈니스 로직을 담당한다.
  • 4. DB와 외부 시스템은 Port와 Adapter를 통해 연결한다.
  • 5. Business 계층은 Django와 특정 외부 서비스에 의존하지 않는다.
READY TO ARCHITECT WITH AI

20강 슬라이드 쉐어로 전체 설계 과정을 복습하세요

강의안의 1장부터 20장까지 모든 코드와 아키텍처 다이어그램을 슬라이드 쉐어 레이어팝업에서 한눈에 넘겨보며 실습할 수 있습니다.

← LMS 과정 홈으로 돌아가기