Add post

Author: minsOne

_posts/2025/06/2025-06-02-architecture-decision-record.md

@@ -0,0 +1,77 @@
+---
+layout: post
+title: "[ADR][가상] 아키텍처 의사 결정 기록: CI 빌드 시간 단축을 위한 Tuist Cache 활용 방안"
+tags: [ADR, iOS, CI, Tuist, Build Cache]
+---
+{% include JB/setup %}
+
+## 네트워크 응답 처리 방식 개선: 공용 응답 모델 도입
+
+작성일 : 2025-06-02
+작성자 : 안정민
+
+<h2 id="status">상태</h2>
+
+* 제안됨(Proposed)
+
+<h2 id="context">배경</h2>
+
+
+우리 팀은 현재 네트워크 응답을 처리할 때 **API Raw Response를 받은 후 Mapper를 통해 DTO(Data Transfer Object)로 변환하고, 이를 비즈니스 로직에 적용**하는 방식을 사용하고 있습니다. 이 방식은 네트워크 통신 로직과 비즈니스 로직 간의 **관심사 분리**를 명확히 하고, 외부 API 변경 시 **Mapper를 통해 변경 영향을 최소화**하며, 비즈니스 로직 테스트 시 **Mock DTO 활용이 용이**하다는 장점을 가지고 있습니다.
+
+하지만, 우리는 이 방식에서 다음과 같은 문제점들을 발견했습니다.
+
+* **코드 중복 발생**: 많은 경우 API Response 객체와 비즈니스 로직용 DTO 객체가 동일한 필드를 가지고 있어, 유사한 구조의 클래스를 두 번 정의하는 코드 중복이 빈번하게 발생합니다.
+* **Mapper 코드 작성 및 유지보수 부담**: 단순 필드 매핑을 위한 반복적인 Mapper 코드 작성이 필요하며, Response나 DTO 변경 시 Mapper 코드 또한 함께 수정해야 하는 번거로움이 있습니다.
+
+이러한 문제점들은 개발 시간 증가와 유지보수 포인트 증가로 이어지고 있습니다.
+
+<h2 id="decisions">결정</h2>
+
+**'공용 응답 모델(Common Response Model)' 도입**을 제안합니다.
+
+<h4 id="rationale">이유</h4>
+
+이 제안의 핵심은 API Response 데이터 구조를 정의하는 타입을 별도의 **공용 모듈/패키지에 정의**하고, **네트워크 모듈과 비즈니스 로직이 이 공용 응답 모델을 직접 공유하고 사용**하도록 하는 것입니다. 이렇게 함으로써 중간 단계의 DTO와 이를 변환하는 Mapper를 생략하여 다음과 같은 이점들을 얻을 수 있습니다.
+
+* **코드 중복 대폭 감소**: Response와 거의 동일한 구조의 DTO를 중복으로 정의할 필요가 없어 코드베이스를 더욱 간결하게 유지할 수 있습니다.
+* **Mapper 코드 제거**: 단순 값 복사에 불과했던 Mapper 클래스 및 관련 로직의 작성 및 관리 부담이 해소되어 개발 생산성이 크게 향상될 수 있습니다.
+* **개발 생산성 향상**: 새로운 API 연동 또는 기존 API 변경 시 작업 단계가 줄어들고 보일러플레이트 코드 작성 시간이 단축되어 전반적인 개발 속도를 높일 수 있습니다.
+* **데이터 모델의 일관성**: API 스펙이 비즈니스 요구사항을 잘 반영하는 경우, 네트워크 경계에서의 데이터 왜곡이나 정보 누락 가능성을 줄여 데이터 모델의 일관성을 유지하는 데 도움이 됩니다.
+
+
+<h2 id="consequences">결과 및 영향</h2>
+
+'공용 응답 모델' 도입 시 다음과 같은 사항들을 신중히 고려하고, 필요시 이에 대한 대비책을 마련해야 합니다.
+
+* **결합도 증가 가능성**: 비즈니스 로직이 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 응답 모델 간의 괴리가 큰 경우, 오히려 **복잡도가 증가**할 수 있습니다.
+
+
+
+<h2 id="conclusion">결론</h2>
+
+**코드 중복 감소**와 **개발 생산성 향상**이라는 목표를 달성하기 위해 '공용 응답 모델' 도입을 제안합니다. 이 방식은 특히 API 응답 구조가 안정적이고 비즈니스 로직의 데이터 모델과 거의 일치하는 경우에 큰 이점을 제공할 것으로 기대됩니다.
+
+그러나 **결합도 증가** 및 **비즈니스 로직의 순수성 저해 가능성**과 같은 잠재적 위험에 대해서는 충분히 인지하고, 이를 관리하기 위한 방안을 함께 마련해야 합니다.
+
+<h2 id="notes">노트</h2>
+
+* **참고 자료**: [네트워크 응답 처리 방식 개선 제안 PPT 초안] (내부 문서 링크 또는 공유 위치)
+* **PoC 진행 예정**: 이번 주 내 특정 API 1~2개에 대해 '공용 응답 모델'을 적용하는 PoC(Proof of Concept)를 진행하여 실제 적용 가능성과 영향도를 검증할 예정입니다.
+* **추가 논의 필요 사항**:
+    * 우리 프로젝트의 API 안정성과 변경 빈도를 고려했을 때, 이 방식의 **적용 범위**(전체, 특정 기능, 시범 적용 등)에 대한 구체적인 논의가 필요합니다.
+    * API 변경 시의 **리스크 관리 방안**(예: API 변경 알림 프로세스, 테스트 전략 강화)에 대한 구체적인 계획 수립이 필요합니다.