민소네

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

02 June 2025

네트워크 응답 처리 방식 개선: 공용 응답 모델 도입

작성일 : 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 변경 알림 프로세스, 테스트 전략 강화)에 대한 구체적인 계획 수립이 필요합니다.