프로젝트의 Dependency Hell — 개념, 원인 및 해결 방법

개발에서 Dependency Hell이란

Dependency Hell은 의존성 관리 시스템이 라이브러리 간 버전 충돌을 해결할 수 없는 상황을 설명하는 용어입니다. 프로젝트에 라이브러리 A 버전 1.x와 라이브러리 B 버전 2.x가 필요하지만, A는 C 버전 1.0에 의존하고 B는 C 버전 2.0에 의존하며, C:1.0과 C:2.0은 호환되지 않습니다.

이 문제는 패키지 관리자가 있는 모든 생태계에서 일반적입니다. Android — support library와 AndroidX 간의 Gradle 충돌. iOS — Alamofire의 다른 버전 간 CocoaPods 충돌. Node.js — npm peer dependency 충돌. Python — pip 해결 실패.

최신 의존성 관리자(npm v7+, Gradle 7+, SwiftPM)는 해결 알고리즘을 개선했지만, 수백 개의 전이적 의존성이 있는 경우 충돌을 완전히 제거하는 것은 불가능합니다. Dependency Hell은 “빌드 오류” 범주에서 “위험 관리” 범주로 전환되었습니다.

프로젝트의 의존성 충돌 유형

Diamond dependency — 전형적인 사례입니다. 라이브러리 A는 D:1.0에 의존하고, 라이브러리 B는 D:2.0에 의존합니다. A와 B가 함께 사용되는 경우, 패키지 관리자는 D의 어떤 버전을 설치할지 결정해야 합니다. 대부분의 경우 최대 버전(2.0)이 선택되지만, A가 D:2.0과 호환되지 않는 경우 — 충돌은 해결 불가능합니다.

Version conflict — 요구 사항의 명시적 불일치. A는 Logging >=2.0이 필요하고, B는 Logging <2.0이 필요합니다. 관리자는 두 조건을 모두 만족시킬 수 없습니다. Peer dependency conflict — 플러그인 A는 React 17이 필요하지만, 프로젝트는 획기적인 변경 사항이 포함된 React 18을 사용합니다. npm이 경고를 표시하지만 설치가 진행되어 — 동작을 예측할 수 없게 됩니다.

Transitive dependency hell — 의존성이 직접적이지 않고 간접적인 경우입니다. 개발자는 라이브러리 A가 B에 의존하고, B가 C에 의존한다는 것을 모릅니다. Gradle Dependency Tree — 전체 의존성 체인을 시각화하여 충돌하는 라이브러리가 어디서 오는지 보여주는 도구입니다.

Circular dependency — A가 B에 의존하고 B가 A에 의존하는 경우입니다. 최신 관리자(Gradle, npm)는 빌드 시 순환 의존성을 차단합니다. 해결책 — A와 B가 모두 의존하는 공통 모듈 C를 추출하여 순환을 끊습니다.

의존성 지옥이 발생하는 방식

라이브러리 수의 증가 — 주요 전제 조건입니다. 각 모듈은 직접 및 전이적 의존성을 추가합니다. Jetpack Compose, Firebase, Retrofit 및 Coil을 사용하는 Android 프로젝트에서 전이적 의존성의 수는 쉽게 500을 초과합니다. 각 새 라이브러리는 잠재적 충돌입니다.

동기화되지 않은 업데이트 — 팀이 서로 다른 시점에 라이브러리를 업데이트합니다. 백엔드가 Jackson을 2.15로 업데이트하고, Analytics 팀은 2.12를 사용합니다. 모듈을 통합할 때 충돌이 발생합니다. 해결책 — Gradle BOM 파일 또는 버전 카탈로그의 중앙 집중식 버전(Bill of Materials).

동일 라이브러리의 다른 버전 — 전형적인 상황: 모듈 A는 OkHttp 3.12를 사용하고, 모듈 B는 OkHttp 4.0을 사용합니다. 4.0으로 업그레이드가 모듈 A를 손상시키는 경우, 프로젝트는 두 버전에 갇히게 되어 Java의 classpath 충돌 또는 iOS의 중복 심볼이 발생할 수 있습니다.

프로젝트 문제 진단

Gradle Dependency Tree — `gradle dependencies` 명령은 충돌 표시와 함께 전체 의존성 트리를 출력합니다. 해결된 버전은 Gradle이 선택한 버전을 보여주고, 충돌하는 버전은 화살표로 표시됩니다. 예: `com.squareup.okhttp3:okhttp -> 4.9.3 (*)` — 버전 해결됨, (*) — 중복.

npm ls — Node.js의 유사한 명령입니다. `--all` 플래그는 전체 트리를 표시합니다. Peer dependency 충돌은 경고와 함께 출력됩니다. SwiftPM Graph — `swift package show-dependencies`는 브랜치와 리비전을 포함하여 iOS 프로젝트의 의존성 그래프를 표시합니다.

Dependency Analysis Plugin — Autonomy의 Gradle 플러그인으로 사용되지 않는 의존성과 충돌을 찾습니다. Ben Manes Versions Plugin — 어떤 의존성이 오래되었는지 확인하고 사용 가능한 업데이트를 표시합니다. 두 도구 모두 정기적인 호환성 검사를 자동화합니다.

예: Gradle에서 충돌 분석

// 충돌: 모듈 A는 okhttp 3.x가 필요, 모듈 B는 okhttp 4.x가 필요
dependencies {
    implementation("com.example:module-a:1.0")  // -> okhttp 3.12
    implementation("com.example:module-b:2.0")  // -> okhttp 4.0
}

// 해결책: 특정 버전 강제
configurations.all {
    resolutionStrategy {
        force "com.squareup.okhttp3:okhttp:4.9.3"
    }
}

충돌 해결 도구

Version Catalog (Gradle 7+) — TOML 파일의 중앙 집중식 버전 선언. 모든 모듈이 동일한 라이브러리 버전을 사용합니다. 예: `libs.versions.toml` 파일에 `okhttp = “4.9.3”`이 포함되어 있고, 모든 모듈이 이 카탈로그를 참조합니다. 모듈 간 버전 충돌이 제거됩니다.

Bill of Materials (Spring BOM) — 호환되는 라이브러리 버전이 지정되는 Maven 개념입니다. Google Android 팀은 Jetpack 라이브러리에 Compose BOM을 사용합니다. BOM을 사용하면 모든 Compose 버전이 서로 호환된다는 보장을 받을 수 있습니다.

Renovate와 Dependabot — 의존성 업데이트를 위한 자동 PR 생성기입니다. Renovate는 호환되는 업데이트를 그룹화하고 Docker 이미지를 통해 획기적인 변경 사항을 확인합니다. Dependabot은 GitHub의 내장 솔루션으로, 의존성을 업데이트하고 CI를 통해 호환성을 확인합니다.

의존성 지옥 예방 전략

Semantic Versioning — patch/minor 업데이트에는 caret `^1.2.3`을, patch만을 위해서는 tilde `~1.2.3`을 사용합니다. 그러나 semver도 호환성을 보장하지 않습니다 — 실제 semver 위반은 15%의 경우에서 발생합니다(Luxembourg 대학 연구, 2024). 잠금 파일은 테스트를 통과한 정확한 버전을 고정합니다.

의존성 최소화 — 각 라이브러리는 정당화되어야 합니다. 20줄의 자체 코드로 기능을 구현할 수 있다면 — 라이브러리를 추가하지 마십시오. 예: 날짜 형식 지정 라이브러리(4개의 전이적 의존성) 대신 플랫폼 내장 도구를 사용합니다. “의존성 예산” 규칙 — 프로젝트당 직접 의존성 50개 이하.

정기적인 업데이트 — 1년에 한 번이 아니라 작은 단계로 의존성을 업데이트합니다. Dependabot은 각 업데이트에 대해 PR을 생성합니다. CI는 전체 테스트 스위트를 실행해야 합니다. DevContainer — 의존성 버전이 프로덕션과 일치하는 통합 개발 환경으로, 환경 간 충돌을 제거합니다.