설명서와 실제 제품 — 아키텍처가 코드로 내려앉는 자리

추상·구상

추상(설명서)은 무엇을 할지만 약속한 것이라 메모리에 직접 올라갈 수 없고, 구상(실제 제품)은 그 약속을 실제로 구현한 것이라 메모리에 올라가 동작합니다.

헥사고날에서 Port가 설명서, Adapter가 실제 제품입니다.

헥사고날

Front end / inbound / input / use case / output / outbound / database입니다.

요청이 들어오는 쪽(inbound)과 나가는 쪽(outbound)을 각각 추상(포트)과 구상(어댑터)으로 나눠 use case(핵심 로직)를 가운데 둡니다.

헥사고날

테스트 용이성(가짜 어댑터로 바꿔 끼워 테스트), 기술 교체 유연성(DB나 외부 API를 바꿔도 핵심 로직은 그대로), 유지보수성(경계가 분명해 어디를 고쳐야 하는지 명확)입니다.

셋 다 '핵심 로직이 특정 기술을 모른다'는 사실에서 나옵니다.

패턴

여러 개의 복잡한 하위 시스템 호출을 하나의 단순한 창구(인터페이스) 뒤로 숨기기 때문입니다.

Route(inbound 어댑터)가 요청을 받는 개별 입구라면, gateway는 그 요청들이 내부로 들어가기 전 거치는, 하나로 모인 창구입니다.

패턴

한 사람(한 클래스)이 모든 처리를 다 하지 않고 여러 핸들러가 요청을 순서대로 넘기며 처리해, 각 핸들러의 책임이 명확해지는 것을 얻습니다.

그 대가로 흐름을 추적하려면 여러 핸들러를 오가며 읽어야 하는 부담이 따릅니다.

헥사고날

실행 순서(제어의 흐름)는 Router → UseCase → Repository로 바깥에서 안쪽으로 흐르지만, 의존성(누가 누구의 존재를 아는가)은 인터페이스(Port)를 매개로 안쪽이 바깥쪽을 모르게, 즉 화살표가 안쪽을 향하도록 설계할 수 있다는 뜻입니다.

스스로 확인

추상 클래스는 '무엇을 할지'만 정하고 '어떻게'는 비워둔 설명서이기 때문입니다. 실제로 동작하려면 구현이 채워진 구상 클래스가 되어야 메모리에 올라갈 수 있습니다.

스스로 확인

두 개입니다. 입력 포트(Input Port)와 출력 포트(Output Port)입니다. 나머지 다섯(Front end, inbound, use case, outbound, database)은 구상입니다.

스스로 확인

구현체(Interactor)가 추상 클래스(ABC, 즉 Input Port)를 상속·구현한다는 뜻입니다.

스스로 확인

Outbound Port(코어가 외부에 요청할 때 쓰는 인터페이스)입니다.

스스로 확인

gateway는 여러 요청을 하나로 모으는 창구(Facade 패턴)이고, Route는 개별 요청을 받아 형식을 변환하는 inbound 어댑터입니다.

스스로 확인

요청 검증, 인증·인가 확인, 예외 처리 같은 반복되는 처리 단계입니다(핸들러 체인).

스스로 확인

디버깅이 어려움(로깅으로 대응), 순서에 민감함(체인 순서 문서화), 처리 누락(디폴트 핸들러로 대응)입니다.

스스로 확인

Facade는 여럿을 하나로 모으는 방향이고, CoR은 하나의 요청을 여럿에게 순서대로 넘기는 방향이기 때문입니다.

스스로 확인

Schema는 바깥(클라이언트)의 언어, DTO는 내부 계층 간 약속의 언어, ORM Entity는 DB(테이블)의 언어입니다.

스스로 확인

최소 네 번입니다. DB row → ORM Entity → 도메인 객체 → DTO → 응답 Schema/JSON 순으로 변환됩니다.

스스로 확인

실행 순서(흐름)는 바깥에서 안쪽으로 요청이 들어가지만, 의존성(누가 누구를 아는가)은 추상(Port)을 매개로 안쪽이 바깥을 모르게 설계되기 때문입니다.

스스로 확인

Input Port와 Output Port, 즉 코어가 외부와 접촉하는 두 인터페이스입니다.

스스로 확인

보일러플레이트(__init__ 등)를 줄이고, 값 비교가 쉬워지며, 타입 힌트로 구조가 명확해지기 때문입니다.

스스로 확인

True/False 가 싱글톤이라 파이썬이 bool 의 서브클래싱을 금지하고 있어 TypeError가 납니다.

자주 하는 실수

Repository(추상)는 아무것도 안 합니다. DB에 붙는 것은 PgRepository(구상)입니다.

자주 하는 실수

포트가 없으면 어댑터를 갈아끼울 자리가 없어집니다.

자주 하는 실수

요청이 조용히 사라집니다. 디폴트 핸들러를 반드시 둬야 합니다.

자주 하는 실수

Schema는 바깥의 언어, DTO는 내부 약속의 언어로 역할이 다릅니다.

자주 하는 실수

password 같은 민감 필드가 응답에 새어 나갈 수 있습니다.

자주 하는 실수

코드 관계(아는 관계)입니다. 실제 데이터는 양방향으로 흐릅니다.

용어

백엔드 진입 경로를 하나로 모은 단일 창구입니다.

용어

핸들러는 책임 연쇄의 한 마디(처리하거나 넘김)이고, 디폴트 핸들러는 체인 끝까지 아무도 처리 못 했을 때 대응하는 마지막 마디입니다.

용어

Router–Interactor–Repository–DB 로 층을 나눈 구조입니다.

용어

"이걸 해라"는 의도를 담은 DTO입니다.

용어

다중 상속은 여러 부모 클래스를 동시에 상속하는 것, 믹스인은 단독 사용이 아니라 기능만 주입하기 위한 클래스입니다.

용어

인스턴스 속성을 미리 못 박아 메모리를 아끼는 파이썬 장치입니다.

용어

가이드(Feedforward)는 행동 전 방향을 정하는 규칙·문서에, 센서(Feedback)는 행동 후 결과를 확인하는 테스트·로그·리뷰에 대응합니다.

용어

추상은 설명서(What), 구상은 실제 제품(How)입니다.

용어

유스케이스(입력 포트)의 구현체입니다.

용어

Front end / inbound / input / use case / output / outbound / database입니다.

용어

처리 객체를 사슬로 엮어 처리 못 하면 다음으로 넘기는 행위 패턴입니다.

용어

프록시는 같은 인터페이스로 접근을 제어하는 대리자이고, 어댑터는 서로 다른 인터페이스를 연결해 호환시키는 것입니다.

용어

바깥에서 들어온 데이터의 형식을 검증하는 그릇입니다.