📚 课程目录第3章环境准备与依赖管理

环境准备与依赖管理

说实话，迁移到新审计SDK的第一步，往往不是写代码，而是先把环境收拾利索。我见过不少团队，拿着新SDK的文档就开始改代码，结果编译报错一片——基本都是依赖版本没搞对。

这一章，我们就聊聊怎么装、怎么选、怎么配。没什么玄乎的，就是些实操经验。

SDK的安装方式

新审计SDK的交付方式，目前主要有三种。我按推荐程度排了个序：

方式	适用场景	备注
Maven中央仓库	Java / Kotlin 项目	最推荐，自动处理传递依赖
Gradle Plugin Portal	Android / Kotlin Multiplatform	配合版本目录更佳
手动JAR	老旧项目或离线环境	建议只作为备选方案
本地Module依赖	需要二次开发SDK源码	注意不要泄漏内部接口

我个人习惯优先用中央仓库。为什么呢？因为省心。我自己在迁移一个老项目时，最开始图省事，直接把JAR丢进libs目录，结果日志框架冲突了整整一天。后来切回Maven坐标，一行代码搞定。

一个小技巧： 如果项目用了BOM（Bill of Materials），可以直接引用SDK的BOM坐标，版本号统一管理起来特别方便。

版本选择策略

怎么选版本？这个问题看起来简单，其实踩坑的人特别多。

新SDK的版本命名遵循语义化版本（SemVer），比如 3.2.1：

主版本（3）：不兼容的API变更。升级时一定要看迁移指南。
次版本（2）：向下兼容的功能新增。可以放心升。
修订号（1）：bug修复。闭着眼睛升就行。

我建议你遵循这么几个原则：

不要追求最新。新版本刚发布，可能会有隐藏问题。等至少一个小版本迭代后再上，更稳妥。
尽量选LTS版本。如果SDK标了LTS（长期支持），优先用这个。我在项目中遇到过，选了一个非LTS的版本，三个月后官方直接停止维护，搞得我们紧急升级了两次。
锁定主版本号。比如确定用3.x系列，就不要在依赖里写成 [3.0.0,4.0.0) 这种范围，否则哪天CI自动拉了个4.0.0，你就哭了。

千万注意： 升级主版本时，旧版本的配置文件可能不兼容。我有一个血泪教训——从2.x升到3.x，忘了更新审计规则配置，结果上线后所有数据校验都失效了，还好灰度发现得早。

Maven配置实战

说白了，就是加几行依赖。但细节很重要。

<!-- pom.xml -->
<properties>
    <audit-sdk.version>3.2.1</audit-sdk.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.yourcompany.audit</groupId>
            <artifactId>audit-sdk-bom</artifactId>
            <version>${audit-sdk.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>com.yourcompany.audit</groupId>
        <artifactId>audit-sdk-core</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yourcompany.audit</groupId>
        <artifactId>audit-sdk-report</artifactId>
    </dependency>
</dependencies>

咦，为什么用BOM？其实很简单——以后想升级，只要改一个 audit-sdk.version 就够了。我之前维护的一个多模块项目，没上BOM，每次升级要改十几个pom文件，经常漏改。用了BOM之后，再也没出过版本不一致的问题。

Gradle配置实战

对于Gradle项目，配置方式类似，更简洁些。

// build.gradle.kts
val auditSdkVersion by extra { "3.2.1" }

dependencies {
    implementation(platform("com.yourcompany.audit:audit-sdk-bom:$auditSdkVersion"))
    implementation("com.yourcompany.audit:audit-sdk-core")
    implementation("com.yourcompany.audit:audit-sdk-report")
}

如果你用Gradle 7.4+，推荐用版本目录（Version Catalog）来管理：

// gradle/libs.versions.toml
[versions]
audit-sdk = "3.2.1"

[libraries]
audit-sdk-bom = { group = "com.yourcompany.audit", name = "audit-sdk-bom", version.ref = "audit-sdk" }
audit-sdk-core = { group = "com.yourcompany.audit", name = "audit-sdk-core" }
audit-sdk-report = { group = "com.yourcompany.audit", name = "audit-sdk-report" }

然后在主项目里引用：

dependencies {
    implementation(platform(libs.audit.sdk.bom))
    implementation(libs.audit.sdk.core)
    implementation(libs.audit.sdk.report)
}

这样所有模块的版本都统一了。我个人特别喜欢这种方式，清晰、可追溯。

依赖冲突与修复

这部分是实操里最头疼的。你想想看，新SDK可能会依赖 jackson 2.13，但你的老项目还在用 jackson 2.11，一整合就出问题。

怎么查？

Maven：mvn dependency:tree，看日志，找到冲突的具体传递依赖。
Gradle：./gradlew dependencies --configuration runtimeClasspath

定位到冲突后，一般有三种解法：

排除传递依赖：在SDK依赖上用 <exclusions> 或 exclude，把老版本排除掉。
统一版本约束：强制指定一个兼容的版本。
升级你项目的底层依赖。

我曾经在一个大型Spring Boot项目里遇到审计SDK和内部安全SDK的guava版本冲突。嗯，最后我选择了统一版本，因为审计SDK需要的版本更新，而且兼容性更好。改了之后，运行了三个月，没出问题。

核心思路： 解决冲突时，优先考虑升级而不是降级。新版本通常修复了已知漏洞，一味降级可能会带来安全问题。

环境验证

依赖配完了，怎么确认环境没问题？我建议写一个最小验证程序：

import com.yourcompany.audit.AuditClient;

public class EnvCheck {
    public static void main(String[] args) {
        // 不需要真实连接，只是验证类能加载
        System.out.println("SDK版本: " + AuditClient.getVersion());
        System.out.println("环境就绪！");
    }
}

能正确打印出版本号，说明你的依赖配置没问题。如果报 NoClassDefFoundError 或者 ClassNotFoundException，那肯定是有依赖没下载全，或者排除命令写错了。

嗯，这一章的内容基本就这些了。环境搞定了，后续的编码工作才能顺利进行。不着急，一步一步来。