의존성 꼬임과 복잡도 증가가 만드는 기술적 문제

핵심 진단 질문

• 새 기능 1개 추가에 수정 파일 수가 과도하게 늘어나는가?
• 하위 모듈 변경이 상위 전역 빌드/테스트를 자주 깨는가?
• 의존 그래프에서 순환(cycle) 또는 거대 허브 모듈이 있는가?
• 테스트 더블(mock/stub) 주입이 어렵고 실서비스 의존이 많은가?

문제의 본질

의존성 꼬임은 결국 "변경 전파 비용" 문제다. 결합도가 높고 경계가 흐리면, 작은 변경이 다수 모듈에 연쇄 전파되어 개발 속도와 안정성을 동시에 떨어뜨린다.

왜 빌드/배포가 흔들리는가

• 의존 그래프가 넓고 깊으면 incremental build 이점이 줄어든다.
• 공용 모듈이 비대하면 작은 수정도 다수 타겟을 재컴파일시킨다.
• 서드파티 패키지 버전/옵션 충돌이 상위 타겟으로 전파된다.

왜 테스트가 깨지기 쉬운가

• DI 경계가 약하면 mock 대체가 어려워 실제 네트워크/스토리지에 붙는다.
• 공통 유틸에 비즈니스 로직이 누적되면 테스트 범위가 비정상적으로 커진다.
• 모듈 책임이 겹치면 assertion 포인트가 모호해진다.

// before: 테스트 대체가 어려운 구조
final class UserProfileService {
  private let session = URLSession.shared

  func fetchName(userID: String) async throws -> String {
    let url = URL(string: "https://api.example.com/users/\(userID)")!
    let (data, _) = try await session.data(from: url)
    let dto = try JSONDecoder().decode(UserDTO.self, from: data)
    UserDefaults.standard.set(dto.name, forKey: "cached_name")
    return dto.name
  }
}

// after: 경계를 protocol로 분리해 mock 주입 가능
protocol UserAPIClient {
  func fetchUser(userID: String) async throws -> UserDTO
}

protocol UserNameStore {
  func save(name: String)
}

final class UserProfileService {
  private let apiClient: UserAPIClient
  private let store: UserNameStore

  init(apiClient: UserAPIClient, store: UserNameStore) {
    self.apiClient = apiClient
    self.store = store
  }

  func fetchName(userID: String) async throws -> String {
    let dto = try await apiClient.fetchUser(userID: userID)
    store.save(name: dto.name)
    return dto.name
  }
}

// test: 실제 네트워크/스토리지 없이 순수 단위 테스트
final class MockAPIClient: UserAPIClient {
  var result: Result<UserDTO, Error> = .success(.init(name: "hank"))
  func fetchUser(userID: String) async throws -> UserDTO { try result.get() }
}

final class SpyStore: UserNameStore {
  var saved: String?
  func save(name: String) { saved = name }
}

관련 문서: 이미지/네트워크 파이프라인 문서, ABC 의존 흐름 문서

완화 전략(단기)

• 순환 의존 1개씩 끊기: protocol interface 모듈 분리
• 거대 공용 모듈 분할: 도메인/인프라 경계 재정의
• 이미지/네트워크/스토리지처럼 변동 큰 영역부터 DI 강화
• 테스트 더블 주입 포인트를 feature entry에서 강제

완화 전략(중기)

• 의존성 가이드라인 문서화(허용 방향/금지 방향)
• CI에서 cycle/fan-out 임계치 검사 자동화
• 모듈 오너십 명확화(책임 모호 영역 제거)
• 변경 전파 비용이 높은 모듈부터 단계적 분해

다이어그램: 권장 의존 방향

• 방향이 단방향이면 영향 전파가 아래쪽으로 제한된다.
• Feature 수정 시 App/Core 전체 재조정 가능성이 낮아진다.
• 테스트 더블 주입 지점이 명확해 모듈 테스트 분리가 쉬워진다.

다이어그램: 복잡도 누적 패턴

• 허브(`HUB`) 집중 의존은 fan-in/fan-out을 동시에 키워 재빌드 범위를 확장한다.
• `CORE2 -> FEAT1` 같은 역방향 의존은 레이어 규칙을 깨고 순환 위험을 만든다.
• 작은 기능 변경도 다중 모듈에 전파되어 배포 안정성을 떨어뜨린다.

잘한 점 (Why It Works)

• App / Core / Feature 구분으로 레이어 인식이 명확하다. 이 분류는 의존성 논의 시 책임 경계를 설명하기 쉽다.
• 읽기 순서(기반 → 앱 공통 → feature)를 제시해 온보딩 비용을 줄인다. 구조 복잡도가 높아도 학습 경로가 있으면 진입 장벽이 낮아진다.
• 외부 패키지 매핑을 공개해 “어떤 모듈이 어떤 서드파티에 묶였는지”를 빠르게 파악할 수 있다. 의존성 영향도 분석(업데이트/라이선스/보안)에 유리하다.
• Target / Scheme / Build Configuration 흐름을 문서화해 빌드 실패 원인 추적 시간을 줄인다. 구조 문서가 없는 프로젝트 대비 운영 안정성이 높다.

개선 포인트 (Why It Hurts)

• 일부 상위 모듈에 의존성이 집중되는 허브 구조가 보인다. 허브 모듈 변경 시 재빌드/회귀 범위가 과도하게 커질 위험이 있다.
• Feature가 Core + App 공통 + 다수 외부 패키지를 동시에 참조하는 패턴은 변경 전파를 키운다. 기능 수정이 인프라/공통 레이어까지 파고드는 현상이 발생하기 쉽다.
• 의존 방향 규칙(허용/금지)이 문서 차원 설명에 머무르면 시간이 지나며 위반이 누적된다. CI에서 cycle/fan-out 임계치 검사를 자동화할 필요가 있다.
• 공통 유틸/매니저 모듈이 비대해지면 테스트 더블 주입이 어려워진다. 결과적으로 통합 테스트 의존도가 올라가고 피드백 속도가 느려질 수 있다.