[SWE-006][기초] 계층형·클린·헥사고날 아키텍처 이해하기
페이지 정보
본문
[이번 수업]
프로그램이 커지면 화면, 업무 규칙, 데이터베이스 코드가 얽혀 작은 변경도 여러 파일을 흔듭니다. 이번에는 세 아키텍처를 비교하고 저장 기술을 몰라도 동작하는 메모 등록 기능을 만듭니다. 모양보다 분리 기준과 코드 의존 방향을 판단하는 것이 목표입니다.
[선수지식]
SWE-002의 함수·모듈 분리와 SWE-005의 계약 개념을 알면 좋습니다. Python의 클래스와 생성자를 읽을 수 있으면 실습할 수 있습니다.
[학습목표]
1. 계층과 배포 단위인 티어를 구분한다.
2. 클린 아키텍처의 안쪽 의존 규칙을 설명한다.
3. 포트와 어댑터로 외부 기술을 교체하는 코드를 작성한다.
[핵심개념]
계층형 아키텍처는 코드를 표시, 업무, 데이터 접근처럼 책임별로 나눕니다. 전통 구조는 표시→업무→데이터 접근 순으로 의존합니다. 계층은 한 프로그램의 논리적 구분이고 티어는 서버·프로세스 같은 물리적 배포 단위입니다.
클린 아키텍처는 업무 규칙을 중심에 둡니다. 소스 코드 의존성은 안쪽을 향하므로 중심 코드는 화면·데이터베이스·외부 API를 모릅니다. 중심이 인터페이스를 선언하고 바깥 구현이 따르는 의존성 역전을 쓰며, 실행할 구현은 시작 지점에서 연결합니다.
헥사고날 아키텍처는 같은 생각을 포트와 어댑터로 표현합니다. 포트는 애플리케이션과 외부의 대화 계약이고, 어댑터는 HTTP·명령줄·파일·데이터베이스를 계약에 맞게 번역합니다. 육각형의 여섯 면보다 안쪽 업무와 바깥 기술의 경계가 중요합니다. 교체 가능성·독립 테스트·업무 복잡성이 있는 경계부터 적용해야 불필요한 유지 비용을 피할 수 있습니다.
[따라하기]
아래를 `architecture_demo.py`로 저장합니다.
```python
from typing import Protocol
class NoteStore(Protocol):
def save(self, text: str) -> int: ...
class AddNote:
def __init__(self, store: NoteStore):
self.store = store
def execute(self, text: str) -> int:
cleaned = text.strip()
if not cleaned:
raise ValueError("내용이 비었습니다")
return self.store.save(cleaned)
class MemoryNoteStore:
def __init__(self):
self.notes: list[str] = []
def save(self, text: str) -> int:
self.notes.append(text)
return len(self.notes)
store = MemoryNoteStore()
add_note = AddNote(store)
note_id = add_note.execute("첫 메모")
print(f"저장됨: {note_id} - {store.notes[0]}")
```
macOS·Linux는 `python3 architecture_demo.py`, Windows PowerShell은 `python architecture_demo.py`로 실행합니다. Python 3.9 이상이 필요합니다.
```text
저장됨: 1 - 첫 메모
```
`AddNote`는 업무 흐름, `NoteStore`는 저장 포트, `MemoryNoteStore`는 메모리 어댑터입니다. 마지막 네 줄은 객체 조립부입니다. `AddNote`는 외부 저장 기술을 가져오지 않아 새 어댑터로 바꿀 수 있습니다. `Protocol`은 필요한 메서드 모양을 표현하며 명시적 상속 없이도 정적 타입 검사를 돕습니다.
[흔한 실수]
폴더 이름만 바꾸고 안쪽 코드에서 데이터베이스 패키지를 가져오면 의존 방향은 그대로입니다. 화면 입력이나 데이터베이스 행을 업무 모델로 그대로 쓰지 않습니다. 모든 클래스에 인터페이스를 만들거나 단순 CRUD에 여러 계층을 강요하지 않습니다. 호출 흐름과 소스 코드 의존 방향도 구분해야 합니다.
[보안 주의]
포트가 자동으로 보안 경계가 되지는 않습니다. 입력 어댑터에서 형식·크기·인증을 확인하고 업무 권한 규칙은 코어에도 둡니다. 저장 어댑터는 문자열 결합 SQL 대신 매개변수를 사용하고 비밀값을 코드에 넣지 않습니다. 오류와 로그에 원문이나 내부 구현을 노출하지 마세요. 실습은 본인 로컬의 가상 데이터만 사용합니다.
[직접 해볼 과제]
`NoteStore` 계약은 유지한 채 `FileNoteStore`를 추가해 `notes.txt`에 한 줄씩 저장하세요. `AddNote`는 수정하지 말고 마지막 조립부에서 어댑터만 교체한 뒤 빈 문자열 거부와 정상 저장을 각각 확인합니다.
[확인문제]
1. 논리적 계층과 물리적 티어는 어떻게 다른가요?
2. 클린 아키텍처에서 데이터베이스 구현이 애플리케이션 코어를 의존해야 하는 이유는 무엇인가요?
3. 헥사고날 아키텍처에서 포트와 어댑터는 각각 어떤 역할을 하나요?
[다음 학습]
SWE-007에서는 업무 용어와 규칙을 코드 모델에 담는 도메인 모델링과 DDD 기초를 배웁니다.
[공식 참고 자료]
- 헥사고날 아키텍처 원문: https://alistair.cockburn.us/hexagonal-architecture/
- 계층형·클린 아키텍처 설명: https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures
- 포트와 어댑터 패턴: https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/hexagonal-architecture.html
- Python Protocol 문서: https://docs.python.org/3/library/typing.html#typing.Protocol
프로그램이 커지면 화면, 업무 규칙, 데이터베이스 코드가 얽혀 작은 변경도 여러 파일을 흔듭니다. 이번에는 세 아키텍처를 비교하고 저장 기술을 몰라도 동작하는 메모 등록 기능을 만듭니다. 모양보다 분리 기준과 코드 의존 방향을 판단하는 것이 목표입니다.
[선수지식]
SWE-002의 함수·모듈 분리와 SWE-005의 계약 개념을 알면 좋습니다. Python의 클래스와 생성자를 읽을 수 있으면 실습할 수 있습니다.
[학습목표]
1. 계층과 배포 단위인 티어를 구분한다.
2. 클린 아키텍처의 안쪽 의존 규칙을 설명한다.
3. 포트와 어댑터로 외부 기술을 교체하는 코드를 작성한다.
[핵심개념]
계층형 아키텍처는 코드를 표시, 업무, 데이터 접근처럼 책임별로 나눕니다. 전통 구조는 표시→업무→데이터 접근 순으로 의존합니다. 계층은 한 프로그램의 논리적 구분이고 티어는 서버·프로세스 같은 물리적 배포 단위입니다.
클린 아키텍처는 업무 규칙을 중심에 둡니다. 소스 코드 의존성은 안쪽을 향하므로 중심 코드는 화면·데이터베이스·외부 API를 모릅니다. 중심이 인터페이스를 선언하고 바깥 구현이 따르는 의존성 역전을 쓰며, 실행할 구현은 시작 지점에서 연결합니다.
헥사고날 아키텍처는 같은 생각을 포트와 어댑터로 표현합니다. 포트는 애플리케이션과 외부의 대화 계약이고, 어댑터는 HTTP·명령줄·파일·데이터베이스를 계약에 맞게 번역합니다. 육각형의 여섯 면보다 안쪽 업무와 바깥 기술의 경계가 중요합니다. 교체 가능성·독립 테스트·업무 복잡성이 있는 경계부터 적용해야 불필요한 유지 비용을 피할 수 있습니다.
[따라하기]
아래를 `architecture_demo.py`로 저장합니다.
```python
from typing import Protocol
class NoteStore(Protocol):
def save(self, text: str) -> int: ...
class AddNote:
def __init__(self, store: NoteStore):
self.store = store
def execute(self, text: str) -> int:
cleaned = text.strip()
if not cleaned:
raise ValueError("내용이 비었습니다")
return self.store.save(cleaned)
class MemoryNoteStore:
def __init__(self):
self.notes: list[str] = []
def save(self, text: str) -> int:
self.notes.append(text)
return len(self.notes)
store = MemoryNoteStore()
add_note = AddNote(store)
note_id = add_note.execute("첫 메모")
print(f"저장됨: {note_id} - {store.notes[0]}")
```
macOS·Linux는 `python3 architecture_demo.py`, Windows PowerShell은 `python architecture_demo.py`로 실행합니다. Python 3.9 이상이 필요합니다.
```text
저장됨: 1 - 첫 메모
```
`AddNote`는 업무 흐름, `NoteStore`는 저장 포트, `MemoryNoteStore`는 메모리 어댑터입니다. 마지막 네 줄은 객체 조립부입니다. `AddNote`는 외부 저장 기술을 가져오지 않아 새 어댑터로 바꿀 수 있습니다. `Protocol`은 필요한 메서드 모양을 표현하며 명시적 상속 없이도 정적 타입 검사를 돕습니다.
[흔한 실수]
폴더 이름만 바꾸고 안쪽 코드에서 데이터베이스 패키지를 가져오면 의존 방향은 그대로입니다. 화면 입력이나 데이터베이스 행을 업무 모델로 그대로 쓰지 않습니다. 모든 클래스에 인터페이스를 만들거나 단순 CRUD에 여러 계층을 강요하지 않습니다. 호출 흐름과 소스 코드 의존 방향도 구분해야 합니다.
[보안 주의]
포트가 자동으로 보안 경계가 되지는 않습니다. 입력 어댑터에서 형식·크기·인증을 확인하고 업무 권한 규칙은 코어에도 둡니다. 저장 어댑터는 문자열 결합 SQL 대신 매개변수를 사용하고 비밀값을 코드에 넣지 않습니다. 오류와 로그에 원문이나 내부 구현을 노출하지 마세요. 실습은 본인 로컬의 가상 데이터만 사용합니다.
[직접 해볼 과제]
`NoteStore` 계약은 유지한 채 `FileNoteStore`를 추가해 `notes.txt`에 한 줄씩 저장하세요. `AddNote`는 수정하지 말고 마지막 조립부에서 어댑터만 교체한 뒤 빈 문자열 거부와 정상 저장을 각각 확인합니다.
[확인문제]
1. 논리적 계층과 물리적 티어는 어떻게 다른가요?
2. 클린 아키텍처에서 데이터베이스 구현이 애플리케이션 코어를 의존해야 하는 이유는 무엇인가요?
3. 헥사고날 아키텍처에서 포트와 어댑터는 각각 어떤 역할을 하나요?
[다음 학습]
SWE-007에서는 업무 용어와 규칙을 코드 모델에 담는 도메인 모델링과 DDD 기초를 배웁니다.
[공식 참고 자료]
- 헥사고날 아키텍처 원문: https://alistair.cockburn.us/hexagonal-architecture/
- 계층형·클린 아키텍처 설명: https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures
- 포트와 어댑터 패턴: https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/hexagonal-architecture.html
- Python Protocol 문서: https://docs.python.org/3/library/typing.html#typing.Protocol
- 이전글[MOBILE-006][기초] 로컬 저장·캐시·오프라인 흐름 이해하기 26.09.02
- 다음글[DATA-006][기초] 평균·분산·상관계수를 올바르게 해석하기 26.09.02
댓글목록
등록된 댓글이 없습니다.