📚 课程目录第4章 SDK获取

第4章 SDK获取：Maven/Gradle依赖配置、手动下载jar包、版本选择策略

4.1 获取SDK到底有哪几条路？

我刚开始做数据安全那会儿，第一反应是找官网下载。后来发现，真正搞工程化，依赖管理才是正路。说白了，你选哪种方式，取决于团队的基础设施和网络环境。通常就三种：Maven中央仓库、Gradle声明、或者直接下载jar往项目里塞。我个人习惯：能走中央仓库就别手动，能配锁文件就别写死版本。

4.2 Maven 依赖配置

先把坐标放对地方。你打开 pom.xml，在 <dependencies> 里面加一段。以审计SDK为例，group 和 artifact 通常会写在公司域名反转后面。版本号我建议用属性统一管理，方便批量升级。

<dependency>
    <groupId>com.yourcompany.security</groupId>
    <artifactId>data-audit-sdk</artifactId>
    <version>${data.audit.version}</version>
</dependency>

然后在 <properties> 里定义版本号：

<properties>
    <data.audit.version>2.3.1.RELEASE</data.audit.version>
</properties>

一个小技巧： 我习惯把依赖放到 <dependencyManagement> 里统一管版本，子模块只写 groupId 和 artifactId，这样升级时改一处就行。

4.3 Gradle 依赖配置

遇到用 Gradle 的项目，写法更简洁。不过要注意，Gradle 的依赖传递默认是开启的，审计SDK如果依赖了某个低版本的日志库，可能会和你的项目冲突。我在项目中遇到过两次这种问题，后来老老实实用 implementation + exclude。

dependencies {
    implementation('com.yourcompany.security:data-audit-sdk:2.3.1.RELEASE') {
        exclude group: 'ch.qos.logback', module: 'logback-classic'
    }
}

如果你用 Kotlin DSL，可以写成：

implementation("com.yourcompany.security:data-audit-sdk:2.3.1.RELEASE") {
    exclude(group = "ch.qos.logback", module = "logback-classic")
}

注意： 别把 compile 和 api 用错。Gradle 7.0 之后 compile 被废弃了，请用 implementation，除非你明确要暴露给下游。

4.4 手动下载 jar 包，什么时候用？

嗯，现实永远不完美。有的公司内网和公网隔离，你不能访问 Maven 中央仓库。这时候就得手动下载 jar 包，然后放到项目的 libs 目录下。我曾经在一个金融项目里，所有外部依赖都得走人工审批流程才能下载，那叫一个折腾。

手动操作步骤很简单：

从发行页面或内部仓库下载 .jar 文件和 pom 文件。
把 jar 放到 src/main/resources/lib 或项目根目录下的 libs/ 里。
在构建工具里把本地 jar 引入。

Maven 下这样配：

<dependency>
    <groupId>com.yourcompany.security</groupId>
    <artifactId>data-audit-sdk</artifactId>
    <version>2.3.1.RELEASE</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/data-audit-sdk-2.3.1.jar</systemPath>
</dependency>

Gradle 里更简单：

implementation fileTree(dir: 'libs', include: ['*.jar'])

    但我得提醒你： 强烈不建议在生产项目里长期用 system scope 或本地 jar，因为版本升级时很容易忘掉手动拷贝，而且 CI/CD 流程里还得单独处理这些文件。

4.5 版本选择策略——别踩坑

到了选版本这一步，很多新手会直接拉最新的。你想想看，新版本意味着新功能，但也可能带来不兼容的 API 变更。我见过一个团队因为用了 2.4.0-SNAPSHOT，结果某天远程仓库清掉了快照缓存，整个构建直接挂掉。

我这里给一个通用的选择优先级：

优先级	版本类型	适用场景
1	RELEASE / GA	绝大多数生产项目，稳定、经过充分测试
2	M1 / RC	预发布版本，可以在非核心环境试用
3	SNAPSHOT	仅限本地开发或临时验证，千万别上生产

还要关注版本号的语义。如果是 1.2.3 格式，通常遵循语义化版本：

主版本号：不兼容的 API 更新，升级后需要改代码。
次版本号：向下兼容的新功能。
修订号：Bug 修复。

避坑指南： 我曾经选了一个次版本号最新的 RC 版本，结果它内部依赖的序列化库从 Jackson 换成了 Gson，导致下游所有模块都在报 NoClassDefFoundError。从那以后，我坚持先看 Release Notes，再看 Breaking Changes，最后才决定升级。

4.6 整章知识结构一览

下面这张图帮你梳理整个 SDK 获取和版本选择的流程。建议你把它贴在团队的技术 wiki 里。

4.7 小结一下

SDK 获取这件事看似简单，但细节里藏着不少坑。记住三条：优先用中央仓库、版本锁定而不是写死、RELEASE 版本最省心。如果能做到这三点，你至少不会踩到依赖版本冲突或快照丢失这种低级问题。后面几章我们会具体聊集成配置和日志埋点，到时候你会看到版本选对了，调试起来有多舒服。