<div id="readability-page-1" class="page"><div>
    <p><span>02 June 2025</span>
    </p>
    <div>
      
<h2 id="네트워크-응답-처리-방식-개선-공용-응답-모델-도입">네트워크 응답 처리 방식 개선: 공용 응답 모델 도입</h2>

<p>작성일 : 2025-06-02
작성자 : 안정민</p>

<h2 id="status">상태</h2>

<ul>
  <li>제안됨(Proposed)</li>
</ul>

<h2 id="context">배경</h2>

<p>우리 팀은 현재 네트워크 응답을 처리할 때 <strong>API Raw Response를 받은 후 Mapper를 통해 DTO(Data Transfer Object)로 변환하고, 이를 비즈니스 로직에 적용</strong>하는 방식을 사용하고 있습니다. 이 방식은 네트워크 통신 로직과 비즈니스 로직 간의 <strong>관심사 분리</strong>를 명확히 하고, 외부 API 변경 시 <strong>Mapper를 통해 변경 영향을 최소화</strong>하며, 비즈니스 로직 테스트 시 <strong>Mock DTO 활용이 용이</strong>하다는 장점을 가지고 있습니다.</p>

<p>하지만, 우리는 이 방식에서 다음과 같은 문제점들을 발견했습니다.</p>

<ul>
  <li><strong>코드 중복 발생</strong>: 많은 경우 API Response 객체와 비즈니스 로직용 DTO 객체가 동일한 필드를 가지고 있어, 유사한 구조의 클래스를 두 번 정의하는 코드 중복이 빈번하게 발생합니다.</li>
  <li><strong>Mapper 코드 작성 및 유지보수 부담</strong>: 단순 필드 매핑을 위한 반복적인 Mapper 코드 작성이 필요하며, Response나 DTO 변경 시 Mapper 코드 또한 함께 수정해야 하는 번거로움이 있습니다.</li>
</ul>

<p>이러한 문제점들은 개발 시간 증가와 유지보수 포인트 증가로 이어지고 있습니다.</p>

<h2 id="decisions">결정</h2>

<p><strong>‘공용 응답 모델(Common Response Model)’ 도입</strong>을 제안합니다.</p>

<h4 id="rationale">이유</h4>

<p>이 제안의 핵심은 API Response 데이터 구조를 정의하는 타입을 별도의 <strong>공용 모듈/패키지에 정의</strong>하고, <strong>네트워크 모듈과 비즈니스 로직이 이 공용 응답 모델을 직접 공유하고 사용</strong>하도록 하는 것입니다. 이렇게 함으로써 중간 단계의 DTO와 이를 변환하는 Mapper를 생략하여 다음과 같은 이점들을 얻을 수 있습니다.</p>

<ul>
  <li><strong>코드 중복 대폭 감소</strong>: Response와 거의 동일한 구조의 DTO를 중복으로 정의할 필요가 없어 코드베이스를 더욱 간결하게 유지할 수 있습니다.</li>
  <li><strong>Mapper 코드 제거</strong>: 단순 값 복사에 불과했던 Mapper 클래스 및 관련 로직의 작성 및 관리 부담이 해소되어 개발 생산성이 크게 향상될 수 있습니다.</li>
  <li><strong>개발 생산성 향상</strong>: 새로운 API 연동 또는 기존 API 변경 시 작업 단계가 줄어들고 보일러플레이트 코드 작성 시간이 단축되어 전반적인 개발 속도를 높일 수 있습니다.</li>
  <li><strong>데이터 모델의 일관성</strong>: API 스펙이 비즈니스 요구사항을 잘 반영하는 경우, 네트워크 경계에서의 데이터 왜곡이나 정보 누락 가능성을 줄여 데이터 모델의 일관성을 유지하는 데 도움이 됩니다.</li>
</ul>

<h2 id="consequences">결과 및 영향</h2>

<p>‘공용 응답 모델’ 도입 시 다음과 같은 사항들을 신중히 고려하고, 필요시 이에 대한 대비책을 마련해야 합니다.</p>

<ul>
  <li><strong>결합도 증가 가능성</strong>: 비즈니스 로직이 API의 데이터 구조에 직접적으로 의존하게 됩니다. 따라서 API 명세(필드명 변경, 타입 변경, 필드 삭제 등)가 변경되면 해당 ‘공용 Response 모델’을 사용하는 모든 비즈니스 로직에 직접적인 영향이 미칠 수 있습니다. 이는 Mapper가 제공했던 완충 역할이 사라지기 때문이므로, 이에 대한 대응 방안(예: API 변경 알림 프로세스 강화, 테스트 커버리지 확대) 마련이 필요합니다.</li>
  <li><strong>비즈니스 로직의 순수성/독립성 저해 가능성</strong>: API 응답에만 존재하는 불필요한 필드나 API 중심의 명명 규칙(예: <code>user_id</code> vs <code>userId</code>)이 비즈니스 로직에 그대로 노출될 수 있습니다. 이는 비즈니스 관점에서 최적화된 모델을 설계하고 사용할 유연성을 감소시킬 수 있으므로, 공용 모델의 설계에 신중해야 합니다.</li>
  <li><strong>‘공용 응답 모델’의 책임 범위</strong>: 해당 모델은 순수 데이터 구조(POJO, data class 등)여야 하며, 특정 라이브러리(예: JSON 파싱 라이브러리 어노테이션)에 과도하게 의존하지 않도록 주의해야 합니다. 만약 특정 라이브러리에 의존해야 한다면, 해당 라이브러리가 공용 모듈의 일부가 되도록 관리해야 합니다.</li>
  <li><strong>다양한 API 또는 데이터 소스 관리</strong>: 여러 외부 API를 사용하거나, 동일 API의 여러 버전을 지원해야 할 때, 각기 다른 응답 구조를 모두 ‘공용’으로 관리하는 것이 오히려 복잡도를 높일 수 있습니다. 따라서 모든 Response가 ‘공용’으로 적합한지 충분한 검토가 필요합니다.</li>
</ul>

<p>다음과 같은 긍정적 및 잠재적 부정적 영향이 있을 수 있습니다.</p>

<ul>
  <li><strong>긍정적 영향</strong>:
    <ul>
      <li>코드베이스의 크기가 감소하고, 관련 클래스의 복잡도가 줄어들어 <strong>가독성이 향상</strong>됩니다.</li>
      <li>신규 API 연동 및 기존 API 변경 시 개발 소요 시간이 단축되어 <strong>개발 생산성이 증가</strong>합니다.</li>
      <li>Mapper 관련 버그 발생 가능성이 줄어듭니다.</li>
    </ul>
  </li>
  <li><strong>잠재적 부정적 영향</strong>:
    <ul>
      <li>API 명세 변경 시, 비즈니스 로직 계층까지 직접적인 영향이 파급될 수 있어 <strong>더 광범위한 코드 수정</strong>이 필요할 수 있습니다.</li>
      <li>초기에는 비즈니스 로직에 API 종속적인 필드가 노출되는 것에 대한 팀원들의 <strong>적응 기간</strong>이 필요할 수 있습니다.</li>
      <li>API 안정성이 보장되지 않거나, 비즈니스 모델과 API 응답 모델 간의 괴리가 큰 경우, 오히려 <strong>복잡도가 증가</strong>할 수 있습니다.</li>
    </ul>
  </li>
</ul>

<h2 id="conclusion">결론</h2>

<p><strong>코드 중복 감소</strong>와 <strong>개발 생산성 향상</strong>이라는 목표를 달성하기 위해 ‘공용 응답 모델’ 도입을 제안합니다. 이 방식은 특히 API 응답 구조가 안정적이고 비즈니스 로직의 데이터 모델과 거의 일치하는 경우에 큰 이점을 제공할 것으로 기대됩니다.</p>

<p>그러나 <strong>결합도 증가</strong> 및 <strong>비즈니스 로직의 순수성 저해 가능성</strong>과 같은 잠재적 위험에 대해서는 충분히 인지하고, 이를 관리하기 위한 방안을 함께 마련해야 합니다.</p>

<h2 id="notes">노트</h2>

<ul>
  <li><strong>참고 자료</strong>: [네트워크 응답 처리 방식 개선 제안 PPT 초안] (내부 문서 링크 또는 공유 위치)</li>
  <li><strong>PoC 진행 예정</strong>: 이번 주 내 특정 API 1~2개에 대해 ‘공용 응답 모델’을 적용하는 PoC(Proof of Concept)를 진행하여 실제 적용 가능성과 영향도를 검증할 예정입니다.</li>
  <li><strong>추가 논의 필요 사항</strong>:
    <ul>
      <li>우리 프로젝트의 API 안정성과 변경 빈도를 고려했을 때, 이 방식의 <strong>적용 범위</strong>(전체, 특정 기능, 시범 적용 등)에 대한 구체적인 논의가 필요합니다.</li>
      <li>API 변경 시의 <strong>리스크 관리 방안</strong>(예: API 변경 알림 프로세스, 테스트 전략 강화)에 대한 구체적인 계획 수립이 필요합니다.</li>
    </ul>
  </li>
</ul>

    </div>

  
    <ul>
      <li><i></i></li>
      
      


  
     
    	<li><a href="about:/tags.html#ADR-ref">ADR <span>18</span></a></li>
     
    	<li><a href="about:/tags.html#Response%20Model-ref">Response Model <span>1</span></a></li>
     
    	<li><a href="about:/tags.html#DTO-ref">DTO <span>1</span></a></li>
     
    	<li><a href="about:/tags.html#Mapper-ref">Mapper <span>1</span></a></li>
     
    	<li><a href="about:/tags.html#API-ref">API <span>2</span></a></li>
     
    	<li><a href="about:/tags.html#%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC-ref">네트워크 <span>1</span></a></li>
    
  



    </ul>
    

    <hr>
    
    <hr>
    




  </div></div>

민소네

네트워크 응답 처리 방식 개선: 공용 응답 모델 도입
작성일 : 2025-06-02
작성자 : 안정민
상태
제안됨(Proposed)
배경
우리 팀은 현재 네트워크 응답을 처리할 때 API Raw Response를 받은 후 Mapper를 통해 DTO(Data Transfer Object)로 변환하고, 이를 비즈니스 로직에 적용하는 방식을 사용하고 있습니다. 이 방식은 네트워크 통신 로직과 비즈니스 로직 간의 관심사 분리를 명확히 하고, 외부 API 변경 시 Mapper를 통해 변경 영향을 최소화하며, 비즈니스 로직 테스트 시 Mock DTO 활용이 용이하다는 장점을 가지고 있습니다.
하지만, 우리는 이 방식에서 다음과 같은 문제점들을 발견했습니다.
코드 중복 발생: 많은 경우 API Response 객체와 비즈니스 로직용 DTO 객체가 동일한 필드를 가지고 있어, 유사한 구조의 클래스를 두 번 정의하는 코드 중복이 빈번하게 발생합니다.
Mapper 코드 작성 및 유지보수 부담: 단순 필드 매핑을 위한 반복적인 Mapper 코드 작성이 필요하며, Response나 DTO 변경 시 Mapper 코드 또한 함께 수정해야 하는 번거로움이 있습니다.
이러한 문제점들은 개발 시간 증가와 유지보수 포인트 증가로 이어지고 있습니다.
결정
‘공용 응답 모델(Common Response Model)’ 도입을 제안합니다.
이유
이 제안의 핵심은 API Response 데이터 구조를 정의하는 타입을 별도의 공용 모듈/패키지에 정의하고, 네트워크 모듈과 비즈니스 로직이 이 공용 응답 모델을 직접 공유하고 사용하도록 하는 것입니다. 이렇게 함으로써 중간 단계의 DTO와 이를 변환하는 Mapper를 생략하여 다음과 같은 이점들을 얻을 수 있습니다.
코드 중복 대폭 감소: Response와 거의 동일한 구조의 DTO를 중복으로 정의할 필요가 없어 코드베이스를 더욱 간결하게 유지할 수 있습니다.
Mapper 코드 제거: 단순 값 복사에 불과했던 Mapper 클래스 및 관련 로직의 작성 및 관리 부담이 해소되어 개발 생산성이 크게 향상될 수 있습니다.
개발 생산성 향상: 새로운 API 연동 또는 기존 API 변경 시 작업 단계가 줄어들고 보일러플레이트 코드 작성 시간이 단축되어 전반적인 개발 속도를 높일 수 있습니다.
데이터 모델의 일관성: API 스펙이 비즈니스 요구사항을 잘 반영하는 경우, 네트워크 경계에서의 데이터 왜곡이나 정보 누락 가능성을 줄여 데이터 모델의 일관성을 유지하는 데 도움이 됩니다.
결과 및 영향
‘공용 응답 모델’ 도입 시 다음과 같은 사항들을 신중히 고려하고, 필요시 이에 대한 대비책을 마련해야 합니다.
결합도 증가 가능성: 비즈니스 로직이 API의 데이터 구조에 직접적으로 의존하게 됩니다. 따라서 API 명세(필드명 변경, 타입 변경, 필드 삭제 등)가 변경되면 해당 ‘공용 Response 모델’을 사용하는 모든 비즈니스 로직에 직접적인 영향이 미칠 수 있습니다. 이는 Mapper가 제공했던 완충 역할이 사라지기 때문이므로, 이에 대한 대응 방안(예: API 변경 알림 프로세스 강화, 테스트 커버리지 확대) 마련이 필요합니다.
비즈니스 로직의 순수성/독립성 저해 가능성: API 응답에만 존재하는 불필요한 필드나 API 중심의 명명 규칙(예: user_id vs userId)이 비즈니스 로직에 그대로 노출될 수 있습니다. 이는 비즈니스 관점에서 최적화된 모델을 설계하고 사용할 유연성을 감소시킬 수 있으므로, 공용 모델의 설계에 신중해야 합니다.
‘공용 응답 모델’의 책임 범위: 해당 모델은 순수 데이터 구조(POJO, data class 등)여야 하며, 특정 라이브러리(예: JSON 파싱 라이브러리 어노테이션)에 과도하게 의존하지 않도록 주의해야 합니다. 만약 특정 라이브러리에 의존해야 한다면, 해당 라이브러리가 공용 모듈의 일부가 되도록 관리해야 합니다.
다양한 API 또는 데이터 소스 관리: 여러 외부 API를 사용하거나, 동일 API의 여러 버전을 지원해야 할 때, 각기 다른 응답 구조를 모두 ‘공용’으로 관리하는 것이 오히려 복잡도를 높일 수 있습니다. 따라서 모든 Response가 ‘공용’으로 적합한지 충분한 검토가 필요합니다.
다음과 같은 긍정적 및 잠재적 부정적 영향이 있을 수 있습니다.
긍정적 영향:
    
코드베이스의 크기가 감소하고, 관련 클래스의 복잡도가 줄어들어 가독성이 향상됩니다.
신규 API 연동 및 기존 API 변경 시 개발 소요 시간이 단축되어 개발 생산성이 증가합니다.
Mapper 관련 버그 발생 가능성이 줄어듭니다.
잠재적 부정적 영향:
    
API 명세 변경 시, 비즈니스 로직 계층까지 직접적인 영향이 파급될 수 있어 더 광범위한 코드 수정이 필요할 수 있습니다.
초기에는 비즈니스 로직에 API 종속적인 필드가 노출되는 것에 대한 팀원들의 적응 기간이 필요할 수 있습니다.
API 안정성이 보장되지 않거나, 비즈니스 모델과 API 응답 모델 간의 괴리가 큰 경우, 오히려 복잡도가 증가할 수 있습니다.
결론
코드 중복 감소와 개발 생산성 향상이라는 목표를 달성하기 위해 ‘공용 응답 모델’ 도입을 제안합니다. 이 방식은 특히 API 응답 구조가 안정적이고 비즈니스 로직의 데이터 모델과 거의 일치하는 경우에 큰 이점을 제공할 것으로 기대됩니다.
그러나 결합도 증가 및 비즈니스 로직의 순수성 저해 가능성과 같은 잠재적 위험에 대해서는 충분히 인지하고, 이를 관리하기 위한 방안을 함께 마련해야 합니다.
노트
참고 자료: [네트워크 응답 처리 방식 개선 제안 PPT 초안] (내부 문서 링크 또는 공유 위치)
PoC 진행 예정: 이번 주 내 특정 API 1~2개에 대해 ‘공용 응답 모델’을 적용하는 PoC(Proof of Concept)를 진행하여 실제 적용 가능성과 영향도를 검증할 예정입니다.
추가 논의 필요 사항:
    
우리 프로젝트의 API 안정성과 변경 빈도를 고려했을 때, 이 방식의 적용 범위(전체, 특정 기능, 시범 적용 등)에 대한 구체적인 논의가 필요합니다.
API 변경 시의 리스크 관리 방안(예: API 변경 알림 프로세스, 테스트 전략 강화)에 대한 구체적인 계획 수립이 필요합니다.

[ADR][가상] 아키텍처 의사 결정 기록: 네트워크 응답 처리 방식 개선 - 공용 응답 모델 도입

댓글