Clean Spring ‐ Web API Adapter

Entity vs DTO

❗애플리케이션(서비스) 계층의 리턴 타입은 DTO여야 하는가, 엔티티여야 하는가?

• 결론 : 가능하다면 엔티티를 권장한다. 단, 이 결론은 "어디까지 전달되는가"에 따라 조건이 붙는다. 같은 프로세스 안의 어댑터까지는 엔티티, 시스템 밖(HTTP 응답, 메시지)으로 나갈 때는 DTO.

1. "DTO로 변환해야 한다"는 통념과 그 근거

• 엄격한 계층형 아키텍처에는 "각 계층은 바로 다음(하위) 계층에만 의존한다"는 제약이 있다.
• 이 제약을 따르면 도메인 엔티티는 애플리케이션 계층까지만 쓰고, 그 밖으로는 필요한 값만 뽑은 DTO로 전달해야 한다.
• 도메인 로직 유출 : 도메인 메서드를 가진 엔티티가 컨트롤러에 도달하면, 프레젠테이션 코드가 member.activate() 같은 도메인 로직을 직접 실행할 수 있다.
• OSIV와 결합 시 의도치 않은 DB 변경 : OSIV(Open Session In View, Spring Boot 기본 활성화)는 영속성 컨텍스트를 뷰 렌더링까지 열어둔다. 컨트롤러에서 관리 상태 엔티티를 수정하면, 이후 트랜잭션이 시작되는 순간 변경 감지로 DB에 반영될 수 있다.

2. 통념에 대한 반론

• 현대 애플리케이션은 완화된 계층형(relaxed layered)을 쓴다. "바로 다음 계층만" 제약은 엄격 계층형의 규칙이고, 상위 계층이 하위 여러 계층을 볼 수 있게 완화하는 것이 일반적이다. 계층형의 목적은 제약 그 자체가 아니라 관심사 분리를 이룬다. 결합도를 낮추고 인지 과부하를 막아 유지보수성을 높이는 것이다. DTO 변환이 그 목적에 기여하지 못하면 형식적 제약일 뿐이다.
• DTO 변환은 도메인 로직 유출을 막지 못한다. 유출은 엔티티라는 타입의 문제가 아니라 규율의 문제다. DTO만 받아도 컨트롤러에 if (dto.status() == PENDING && ...) 같은 도메인 규칙을 얼마든지 다시 구현할 수 있다. 막는 수단은 변환 계층이 아니라 코드 리뷰와 설계 규율이다.
• 어차피 엔티티는 계층 밖을 이미 다니고 있다. 컨더리 어댑터(리포지토리)는 엔티티를 받고 돌려준다. "엔티티는 도메인/애플리케이션 안에만"이라는 규칙은 아웃바운드 방향에서 이미 성립하지 않는다.
• 변환 비용은 실재한다. 유스케이스마다 DTO + 매핑 코드가 생기고, 필드 추가 시 수정 지점이 늘어난다. 이 비용을 지불할 이유가 있어야 한다.

3. 그럼에도 DTO가 필요한 지점 — 경계의 구분

• 애플리케이션 → 인바운드 어댑터 (프로세스 내부) : 같은 언어, 같은 트랜잭션 문맥. 변환 이득이 없다. 즉, 엔티티로 전달해도 무방하다.
• 어댑터 → 시스템 밖 (HTTP 응답, 메시지, 외부 계약) : 직렬화 문제(LAZY 필드 초기화 폭탄, 순환 참조), 내부 스키마 유출, API 계약의 독립적 진화가 걸린다. 즉, DTO로 전달하는 것을 권장한다.

1. User Interface (Presentation) — 사용자 인터페이스 계층

• 사용자(또는 외부 시스템)에게 정보를 보여주고 명령을 받아들이는 책임을 진다.
• 여기서 "사용자"는 사람만이 아니라 우리 API를 호출하는 다른 시스템도 포함한다.
• HTTP 요청을 해석하고, 응답을 직렬화하고, 인증 토큰을 꺼내는 것까지가 이 계층의 일이고 "회원 등록이 어떤 절차인가"와 같은 저수준은 몰라야 한다.

2. Application — 응용 계층

• 유스케이스의 조율자이다.
• "회원을 등록한다"는 업무 흐름 즉, 중복 검사하고, 도메인 객체를 만들고, 저장하고, 환영 메일을 보낸다는 저수준 순서를 아는 곳이다.
• 핵심은 얇아야 한다는 것이다. 업무 규칙 자체를 판단하지 않고, 판단은 도메인에 시키고 자신은 절차와 트랜잭션 경계만 관리한다.

3. Domain (Model) — 도메인 계층

• 소프트웨어의 심장. 업무 개념, 상태, 규칙이 사는 곳이다.
• "등록 대기 상태에서만 등록 완료가 될 수 있다", "프로필 주소는 15자 이내"와 같은 규칙이 코드로 존재하는 유일한 장소여야 한다.
• 다른 모든 계층은 교체 가능하지만 이 계층이 날아가면 소프트웨어 존재 이유가 사라진다.

4. Infrastructure — 인프라스트럭처 계층

• 위 세 계층을 기술적으로 떠받치는 계층. DB 접근, 메시지 전송, 메일 발송, 프레임워크 연동 등이 있다. "업무가 아니라 기술"인 모든 것이다.
• 특징은 대체 가능성이 있을텐데 MySQL이 PostgreSQL로, SMTP가 SSE로 바뀌어도 업무 규칙은 한 글자도 안 바뀐다.