외부 응답 형식을 내부 도메인 모델과 분리해 API 변경의 충격 범위와 테스트 비용을 줄이는 구조를 정리합니다. 설정부터 시작하기 전에 ‘Transport DTO’을 분리해서 봐야 합니다. 외부 JSON의 필드명과 선택값, 원시 형식을 그대로 표현합니다. 공급자 변경을 내부 도메인 타입에 직접 퍼뜨리지 않는 경계입니다.
이 글의 범위
실제 경험이나 측정 결과를 가정하지 않고, 공식 문서로 확인 가능한 개념과 적용 순서를 일반 가이드로 설명합니다. 제품 버전과 서비스 정책은 바뀔 수 있으므로 적용 전 연결된 공식 문서를 다시 확인하세요.
 |
| DTO와 Normalizer, Composition Layer를 나누는 이유 핵심 판단 흐름 설명용 개념도 |
설정 전에 정리할 문제
DTO, Normalizer, 도메인 모델, Composition Layer의 구분은 파일 수를 늘리기 위한 규칙이 아닙니다. ‘Transport DTO’에서 시작해 ‘검증’와의 경계를 정하면 구현할 범위와 실패했을 때 확인할 지점을 구분하기 쉬워집니다.
기존 직접 사용 코드를 분리하는 순서
- 외부 응답 필드가 사용되는 위치와 업무 의미를 추적합니다.
- 원시 DTO와 도메인 모델을 별도 타입으로 정의합니다.
- 변환 규칙과 유효성 오류를 Normalizer에 모읍니다.
- 여러 데이터 소스의 결합과 대체 규칙을 Composition Layer로 옮깁니다.
- 실제 응답 샘플과 누락·변경된 응답을 계약 테스트로 저장합니다.
외부 응답을 내부 모델로 바꾸는 네 단계
Transport DTO
외부 JSON의 필드명과 선택값, 원시 형식을 그대로 표현합니다. 공급자 변경을 내부 도메인 타입에 직접 퍼뜨리지 않는 경계입니다.
검증
필수 필드와 형식, 허용 범위를 확인하고 누락과 잘못된 값을 구분합니다. 파싱 성공을 데이터 유효성으로 착각하지 않습니다.
Normalizer
날짜, 주소, 코드, 단위처럼 공급자별 표현을 내부 표준으로 바꾸고 변환 근거와 경고를 남깁니다.
Domain Model
화면이나 업무 규칙에 필요한 안정된 개념만 표현합니다. 외부 API의 임시 필드가 앱 전체의 계약이 되지 않게 합니다.
Composition Layer
여러 공급자의 정규화 결과를 조합하고 우선순위, 부분 실패, 캐시 정책을 결정합니다. 단순 DTO 변환과 업무 결정을 분리합니다.
작업 전 확인표
| 확인 항목 | 질문 |
|---|---|
| 첫 기준: Transport DTO | 변경 전에 전제와 목적을 확인했는가? |
| 분리 대상: 검증 | 다른 책임과 섞이지 않게 경계를 정했는가? |
| 피할 패턴: DTO와 도메인 모델이 필드명까지 완전히 같기 | 본문에서 경고한 패턴이 남아 있지 않은가? |
| 오류와 복구 | 정상 경로뿐 아니라 실패와 되돌리기도 확인했는가? |
레이어만 늘리고 효과를 잃는 패턴
- DTO와 도메인 모델이 필드명까지 완전히 같기
- Normalizer에서 네트워크 호출과 DB 저장까지 수행하기
- 잘못된 값을 빈 문자열로 바꿔 오류를 숨기기
- Composition Layer가 공급자별 JSON 구조를 직접 읽기
핵심만 다시 보면
DTO, Normalizer, 도메인 모델, Composition Layer의 구분은 파일 수를 늘리기 위한 규칙이 아닙니다. 외부 변화가 들어오는 경로와 내부 판단이 이루어지는 경계를 명확히 해 변경의 충격과 테스트 범위를 줄이는 방법입니다.
