📚 课程目录第3章环境准备

第3章环境准备：开发环境搭建，依赖管理

环境搭建这事儿，说起来简单，做起来全是坑。我在给团队做合规SDK迁移时，光依赖冲突就折腾了一整天。这一章我们就把Maven、Gradle、npm这三套工具捋清楚，保证你搭完环境就能直接跑合规SDK，不用回头补课。

3.1 IDE与基础工具链

我习惯先装好JDK（Java 11以上），Gradle那边要求至少7.x。但注意一点：合规SDK有些模块还是Java 8兼容的，所以我不推荐一上来就追最新的JDK 21。稳一点，用JDK 11或17，长期支持版少踩坑。

IDE方面，IntelliJ IDEA社区版够用。如果你做Android合规，Android Studio自带Gradle，不用额外装。但我个人更爱用VSCode + 插件，轻量，切项目快。

另外，记得装好Git和Docker。Docker不是必须，但后面做合规扫描时能省很多事。我用它跑预检环境，干净利落。

小提示：我曾经因为IDEA里Gradle版本和项目要求的版本不匹配，整个项目都build不了。检查IDE配置里的Gradle路径，别让IDE自己连网下载，容易乱。

3.2 Maven集成实战——稳定派的选择

Maven是老大哥，公司里Java后端项目八成都在用。合规SDK的官方文档通常优先给Maven示例，你跟着来就好。

首先在pom.xml里加入仓库。很多新手不配仓库，直接照着文档写dependency，结果下载不到。我先贴一个标准配置：

<repositories>
    <repository>
        <id>maven-central</id>
        <url>https://repo.maven.apache.org/maven2</url>
    </repository>
    <!-- 如果你用的是私有仓库或代理，这里加 -->
    <!-- <repository>
        <id>my-company-repo</id>
        <url>https://nexus.mycompany.com/repository/maven-public/</url>
    </repository> -->
</repositories>

<dependency>
    <groupId>com.example.compliance</groupId>
    <artifactId>compliance-sdk-core</artifactId>
    <version>2.3.0</version>
</dependency>

我建议你直接用BOM（Bill of Materials）统一管理SDK版本，尤其是当合规SDK包含多个子模块时。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.example.compliance</groupId>
            <artifactId>compliance-bom</artifactId>
            <version>2.3.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

这样你子模块里写依赖就不用写版本号了。我在一个大型金融项目里这么干，一百多个微服务统一升级版本，改一行就行。

避坑：我曾经在Maven中没配置settings.xml的镜像，导致从中央仓库拉取合规SDK时被公司网络策略拦截。你可以改用阿里云或腾讯云的镜像：<mirrorOf>*</mirrorOf>指向公司内网仓库。

3.3 Gradle配置要点——灵活但容易乱

Gradle比Maven灵活，但灵活也意味着容易擦边走火。合规SDK用Gradle时，我建议直接用官方推荐的方式——kotlin-dsl，配置更安全。

先看最基础的build.gradle.kts：

repositories {
    mavenCentral()
    // 如果用了私有仓库
    // maven { url = uri("https://nexus.mycompany.com/repository/maven-public/") }
}

dependencies {
    implementation("com.example.compliance:compliance-sdk-core:2.3.0")
    // 如果把SDK推到了Maven仓库里，用这个
    // implementation("com.example.compliance:compliance-sdk-core:2.3.0") { changing = true }
}

记住，用implementation而非api，避免泄漏依赖给下游。我见过有人把合规SDK配置成api，结果所有应用模块的类路径都污染了，编译时各种冲突。

如果你要同时支持Java和Android，Gradle版本统一就行。合规SDK本身一般不做特定平台绑定，所以放心用。

经验：Gradle缓存目录默认在~/.gradle/caches，如果换版本后build报错，先清缓存试试。我那次折腾了俩小时，最后发现是缓存里有旧版本的元数据。

3.4 npm与前端合规SDK

前端项目现在也离不开合规条款SDK。像用户许可弹窗、隐私政策版本管理等，前端集成用npm最多。

标准安装：

npm install @your-org/compliance-sdk@latest --save

注意，一定要加--save，否则package.json里不会记录。我习惯用npm ci而不是npm install做锁定安装，保证团队成员都用同一版本。

另外，合规SDK有时候会依赖一些原生模块（比如加密库），这时候你要检查node-gyp配置。我之前在Windows环境上卡过，后来装了Visual Studio Build Tools才跑通。

工具	配置文件	声明依赖方式	依赖范围
Maven	pom.xml	dependency元素	compile/provided/runtime/test
Gradle	build.gradle(.kts)	implementation/api/compileOnly	implementation/api/compileOnly/runtimeOnly/testImplementation
npm	package.json	dependencies/devDependencies/peerDependencies	dependencies / devDependencies

3.5 多语言项目的统一管理

如果你的项目既有Java后端（Maven），又有Android客户端（Gradle），还带着前端（npm），怎么保证合规SDK版本一致？

我个人习惯是在项目根目录放一个VERSION文件，里面只写一行版本号。然后用CI脚本去读取，再通过环境变量注入各个构建脚本。这样做的好处是改一个地方，所有语言都同步。

举个例子，我在一个微服务+Flutter的混合项目里用过，Jenkins Pipeline里读这个文件，Maven用-Dcompliance.version=$(cat VERSION)，Gradle用ext.complianceVersion = System.getenv('COMPLIANCE_VERSION')，npm用npm install @our/compliance-sdk@"${COMPLIANCE_VERSION}"。

核心结论：无论你用哪种工具，先确认仓库可达，再锁定版本，最后做一次compile验证。这个流程走一遍，环境就稳了。我不会省略“clean + compile”这一步，曾经因为跳过它直接跑测试，结果依赖没下载到，报错一堆，但测试报告居然显示通过……吓人。

📚 课程目录

第3章 环境准备：开发环境搭建，依赖管理

3.1 IDE与基础工具链

3.2 Maven集成实战——稳定派的选择

3.3 Gradle配置要点——灵活但容易乱

3.4 npm与前端合规SDK

3.5 多语言项目的统一管理

第3章环境准备：开发环境搭建，依赖管理