📚 课程目录第4章依赖管理

4. 依赖管理：Maven、Gradle、npm、CocoaPods 工具使用

说到 SDK 集成，绕不开的就是依赖管理。没有它，你手动下载 jar 包、改 classpath，累死不说，还容易版本冲突。我早期做 Android 时就是纯手动，后来被一个间接依赖的 Jackson 版本冲突搞到崩溃，才彻底转投 Gradle。今天聊聊四个主流工具：Maven、Gradle、npm 和 CocoaPods。它们背后思路一样，但用法和生态差别挺大。

核心目标：声明依赖 → 工具自动解析传递依赖 → 统一仓库获取 → 构建后生成锁定文件，确保可复现。

4.1 工具概览与适用场景

先别急着记命令。你想想看，每种工具都对应一个生态：Maven 稳，Java 老项目标配；Gradle 活，Android 和现代 Java 都在用；npm 是前端和 Node.js 的门面；CocoaPods 则是 iOS 的标配。我个人的习惯是：跨平台 SDK 如果面向 Java/Android，优先给 Gradle 示例；面向前端给 npm；面向 iOS 给 Podfile。

工具	语言/平台	配置文件	锁定文件	仓库管理
Maven	Java, Kotlin	pom.xml	无（但可用 enforcer 插件）	Maven Central, JCenter（已停）
Gradle	Java, Android, Kotlin	build.gradle / build.gradle.kts	gradle.lockfile	Maven Central, Google, JitPack
npm	JavaScript, TypeScript	package.json	package-lock.json	npm registry
CocoaPods	Swift, Objective-C	Podfile	Podfile.lock	Trunk / CDN

4.2 Maven：老牌稳定的依赖大树

Maven 用的是 XML，配置冗长但结构清晰。以前我在一个银行项目里，几十个模块全用 Maven，虽然慢但从来没翻车。它的依赖传递规则很经典：最短路径优先，第一声明优先。不过要注意，Maven 默认没有依赖锁定文件，多人协作时容易「我本机编译过，你那边断了」——解决方案是用 maven-enforcer-plugin 加上 dependency-convergence 规则。

<!-- pom.xml 示例 -->
<dependencies>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>my-sdk</artifactId>
        <version>2.1.0</version>
    </dependency>
</dependencies>

我最常用 mvn dependency:tree 来看完整的依赖树，定位冲突特别快。

4.3 Gradle：灵活跟手，但注意性能

Gradle 兼容 Maven 仓库，但使用 Groovy 或 Kotlin DSL，配置更简洁。我搞 Android 集成时，经常在 build.gradle 里写 implementation 而不是 api——前者依赖不会泄漏给调用方，避免巨大版本冲突。Gradle 的缓存机制很强大，但如果你用了太多动态版本（2.+），构建就会变慢且不可预测。

// build.gradle.kts 示例
dependencies {
    implementation("com.example:my-sdk:2.1.0")
    // 传递依赖控制
    implementation("com.fasterxml.jackson.core:jackson-databind") {
        version { strictly("2.14.2") }
    }
}

曾经有个项目把 compile 和 api 混着用，版本满天飞。记住：团队内部统一 scope 使用规范，否则排错排到哭。

4.4 npm：扁平化与幽灵依赖

npm 的依赖管理很有趣，早期是嵌套 node_modules，后来改成扁平加符号链接。它的 package-lock.json 是神器，任何成员 npm install 后得到的依赖树完全一致。但我踩过一个坑：某个间接依赖声明了 ^1.2.0，结果一个小版本带了 breaking change，线上挂了。现在我的标准做法是用 npm audit 检查安全漏洞，同时用 npm ci 代替 install 在 CI 里保证精确安装。

// package.json 示例
{
  "dependencies": {
    "my-sdk": "^2.1.0"
  }
}

避坑：别轻易在 package.json 里写 * 版本，那等于把控制权交给上游。我用 npm shrinkwrap 生成锁定文件之前，先和团队约定好只提交 package-lock.json。

4.5 CocoaPods：iOS 领域的依赖守护

CocoaPods 的 Podfile 看起来像 Ruby 脚本，依赖全部解析到 Pods/ 文件夹下。我个人觉得它的设计很棒：通过 use_frameworks! 开关就能决定是否使用动态 framework。但有个痛点：如果两个 pod 依赖同一个库的不同版本，CocoaPods 会直接报错，不像 npm 那么宽容。这时你得手动强制指定版本。

# Podfile 示例
platform :ios, '12.0'
target 'MyApp' do
  use_frameworks!
  pod 'MySDK', '~> 2.1'
  # 强制解决冲突
  pod 'Alamofire', '5.6.0'
end

我在集成第三方 SDK 时总会先 pod repo update，确保本地 spec 仓库是最新的，免得遇到 404。

4.6 一张图读懂多场景依赖管理

下面这张图总结了四个工具的定位和常见问题，你看一遍就能理清思路。

4.7 常见陷阱与我的处置方式

依赖管理说穿了就三件事：版本声明、传递解析、锁定。但实际落地处处是坑。我把常见问题列出来，你对照着看。

版本冲突——Maven 用最短路径，Gradle 用最新版本策略，npm 用扁平化加符号链接。我一般直接用 dependency:tree 或 ./gradlew dependencies --configuration runtimeClasspath 打印后定位，再在配置里强制指定版本。
锁定文件丢失——Git 一定要提交 package-lock.json 或 Podfile.lock，否则同事买票不同结果。Gradle 需要通过 dependencyLocking 插件开启。
动态版本滥用——比如 2.1.+ 或 ^2.1.0 带来的不可预测性。我曾经被 2.1.3 偷偷修复了一个 bug，但另一个模块却依赖旧行为，直接崩了。现在我都用精确版本。
私服仓库配置——公司内部 SDK 需要部署到私有 Maven 仓库或 npm 私有仓库。记得在 settings.xml 或 .npmrc 里配好认证，不然 CI 编译失败。

千万别把 node_modules 或 .gradle 目录提交到版本库！忘了写 .gitignore 会让你仓库变得臃肿无比，而且团队成员无法保证本地环境一致。

4.8 总结与个人建议

依赖管理没有银弹，但每个工具有自己舒服的姿势。我个人习惯是：Java/Android 新项目一律 Gradle + Kotlin DSL + 锁定文件；前端项目严格走 npm ci；iOS 项目 Podfile 写上明确的版本约束。你想想看，这些都是花一次时间配好就能长期受益的事，别忽略它。

最后留一句话：依赖管理的本质是信任管理——信任你的仓库，信任你的锁定文件，更信任你的团队规范。嗯，这章就到这。