Search
🌍

작은 규모에서는 유즈케이스의 인터페이스를 만들지 마라.

이 글에서는 인프라 레이어와 애플리케이션 레이어가 만나는 지점에 집중합니다. 교과서적인 헥사고날 아키텍처는 다음과 같은 구조를 가집니다. 입력 포트는 ‘유즈케이스의 호출 인터페이스’이고, 유즈케이스는 그 인터페이스가 대표하는 애플리케이션 동작 자체(또는 그 구현체)입니다. (사람에 따라 유즈케이스를 입력 포트이자 인터페이스로 표현하는 경우도 있습니다(ref1))
classDiagram
    direction LR
    class FastAPI_Adapter {
        +add_song()
    }
    class AddSongPort {
        <<interface>>
        +execute()
    }
    class AddSongUseCase {
        +execute()
    }

    FastAPI_Adapter --> AddSongPort : 의존/호출
    AddSongUseCase ..|> AddSongPort : 구현
Mermaid
복사
헥사고날 아키텍처 개념에서 포트의 역할은 유즈케이스의 구현을 허용하는 것입니다. 즉, 입력 포트(Input Port)를 굳이 만드는 정석적인 방식은 유즈케이스 구현체가 다양함에도 호출 규격을 안정적으로 고정하고 싶은 경우 비로소 빛을 발합니다. 구현체가 하나뿐이라면 인터페이스는 불필요한 보일러플레이트가 됩니다.
classDiagram
    class FastAPI_Adapter {
        +add_song()
    }
    class AddSongUseCase {
        +execute()
    }

    FastAPI_Adapter --> AddSongUseCase : 의존/호출
Mermaid
복사
의존성의 방향이 안쪽을 향하는 정도면 충분합니다. 가령 애플리케이션 레이어는 프레임워크 타입(FastAPI Request/HTTPException 등)에 의존하지 않아야 합니다. 요청/응답 변환과 HTTP 예외 매핑은 어댑터의 책임으로 두면 경계가 선명해집니다.
또 한 걸음 더 실용적으로 가면, 애플리케이션 레이어가 반환하는 값의 타입도 꼭 순수 DTO일 필요는 없습니다.
classDiagram
    class FastAPI_Adapter {
        +add_song()
    }
    class CLI_Adapter {
        +add_song()
    }
    class MessageConsumer_Adapter {
        +handle_add_song()
    }

    class AddSongUseCase {
        +execute()
    }

    FastAPI_Adapter --> AddSongUseCase : 의존/호출
    CLI_Adapter --> AddSongUseCase : 의존/호출
    MessageConsumer_Adapter --> AddSongUseCase : 의존/호출
Mermaid
복사
반환하는 값의 타입이 순수 DTO인 경우는 이처럼 진입 채널이 여러 개로 확장할 가능성이 있는 경우 빛을 발합니다. 하지만 대부분의 시스템의 진입 채널은 HTTP입니다. 프레임워크의 경우에도 FastAPI같이 든든한 국밥을 선택한 이후에는 바꿀 일이 거의 없습니다.
이처럼 시스템의 입력을 다른 채널로 확장하거나 변경할 가능성이 거의 없다면, 응답 스키마를 조립하는 책임을 애플리케이션 레이어에서 끝내는 선택이 가능합니다. 이 경우 유즈케이스는 SongDto 같은 중간 DTO를 반환하는 대신, 곧바로 AddSongResponse 같은 “응답 전용 모델”을 만들어 반환합니다. 어댑터가 DTO를 풀어서 Response로 재구성하는 작업 없이 그대로 반환만 하면 되므로 코드량과 실수 지점을 크게 줄일 수 있습니다.
parse me : 언젠가 이 메모에 쓰이면 좋을 것 같은 재료들입니다.
1.
None
from : 이 메모에 쓰인 생각을 만든 과거의 생각들과 연관관계를 설명합니다.
1.
•
앞의 글은 포트와 어댑터의 개념에 대해 설명한다.
2.
•
작은 규모의 프로젝트에서는 “이 프로젝트의 경우 시스템의 진입점과 웹 프레임워크가 변경될 일이 거의 없으므로, 애플리케이션 계층이 컨트롤러로 값을 반환할 때 중간 DTO를 반환하는 대신, 곧바로 Response를 만들어 반환한다. 어댑터가 DTO를 풀어서 Response로 재구성하는 작업 없이 그대로 반환만 하면 되므로 코드량과 실수 지점을 크게 줄일 수 있다.”라는 가이드를, 큰 규모의 프로젝트에서는 “이 프로젝트의 경우 시스템의 진입점과 웹 프레임워크가 변경될 수 있으므로, 애플리케이션 계층이 컨트롤러로 값을 반환할 때 곧바로 Response를 만들어 반환하는 대신 중간 DTO를 반환한다.”라는 가이드를 추가했다.
supplementary : 이 메모에 작성된 생각을 뒷받침하는 새로운 메모입니다.
1.
None
opposite : 이 메모에 작성된 생각과 대조되는 새로운 메모입니다.
1.
None
to : 이 메모에 작성된 생각으로부터 발전된 생각의 메모입니다.
ref : 생각에 참고한 자료입니다.
영구메모 템플릿 버전 2025.11.16