📚 课程目录第3章环境准备与依赖配置

3. 环境准备与依赖配置

大家知道，搭好环境是开始一切工作的基础。说实话，我在辅导团队接入SDK时，发现大部分问题都卡在环境配置上，而不是代码逻辑。你想想看，如果JDK版本不对，后面代码怎么调都跑不起来，那不是白费功夫吗？

所以这一章，咱们就把开发环境、依赖管理工具，还有常见的坑，一一说清楚。我自己的习惯是，每次开新项目都会先把环境检查一遍，形成一个checklist，这样后面才能专心写核心逻辑。

3.1 开发环境要求

我们的实时风险监测SDK对开发环境有明确要求。说白了，就是得保证你的电脑能跑得动，不卡壳。

组件	推荐版本	说明
操作系统	Linux (CentOS 7+ / Ubuntu 18.04+)	生产环境必须用Linux，性能最稳。
操作系统	macOS 10.15+	适合开发调试，我日常就用这个。
操作系统	Windows 10+ (WSL2)	实在不行就用WSL2，别直接在cmd跑。
JDK	JDK 11 (LTS) / JDK 17 (LTS)	SDK核心用Java写的，务必64位版本。
Python	Python 3.8+	用于自动化部署脚本和部分数据处理。

嗯，这里要注意一下。JDK版本不能低于8，否则SDK里依赖的NIO和异步特性会出错。我早期踩过坑，用JDK 8去编译，结果运行时报了一大堆兼容性问题，后来才发现是版本不对。

警告：千万别用JDK 8！虽然也能编译，但运行时会报 java.lang.NoSuchMethodError，因为SDK里的某些底层接口在JDK 11才支持。

3.2 依赖管理工具

依赖管理工具，说白了就是帮我们管理jar包、处理版本冲突的。我建议你至少熟悉一种：Maven 或 Gradle。我个人更倾向于Maven，因为项目结构清晰，大家上手快。

Maven 配置要点

Maven的核心是 pom.xml。我的习惯是做好以下几件事：

指定仓库地址：优先用阿里云镜像，不然下载慢得像蜗牛。
锁定依赖版本：用 <properties> 统一管理版本号。
排除冲突依赖：引入第三方包时，把内部自带的旧版日志框架排除掉。

Gradle 配置要点

Gradle配置更简洁，如果你喜欢用Kotlin DSL，可以这样写：


repositories {
    maven { url 'https://maven.aliyun.com/repository/public' }
    mavenCentral()
}

dependencies {
    implementation 'com.example:risk-monitor-sdk:1.2.0'
    // 排除传递依赖中的冲突版本
    implementation('ch.qos.logback:logback-classic:1.2.11') {
        exclude group: 'org.slf4j', module: 'slf4j-api'
    }
}

说实话，Gradle的增量编译确实快，但团队统一就好，没必要纠结用哪个。

3.3 基础依赖引入

现在咱们来动手引入核心依赖。以Maven为例，先在 pom.xml 里做几件事：

添加阿里云镜像：在 <repositories> 里配置，速度提升巨大。
引入实时风险监测SDK：坐标如下：
引入日志框架：我们的SDK使用SLF4J + Logback，你需要引入对应依赖，避免日志被吞。


<!-- pom.xml 核心片段 -->
<properties>
    <risk-monitor.version>1.2.0</risk-monitor.version>
    <slf4j.version>1.7.36</slf4j.version>
</properties>

<dependencies>
    <!-- 实时风险监测SDK -->
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>risk-monitor-sdk</artifactId>
        <version>${risk-monitor.version}</version>
    </dependency>

    <!-- 日志 -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>${slf4j.version}</version>
    </dependency>
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.2.11</version>
    </dependency>
</dependencies>

小技巧：如果依赖下载慢，可以试试在 settings.xml 里配置阿里云镜像的Profiles，全局生效。

3.4 环境验证流程

依赖引入完成后，别急着写业务代码。先做一个环境检查，确保SDK能正常加载。这是我的标准流程：

运行 mvn clean install，看看依赖是否全部下载完成。
写一个小Demo，初始化SDK连接，看日志输出是否有异常。
检查SDK版本号是否正确，别引成了测试版。

为什么要这么做？你想想看，如果环境都没跑通，后面写了1000行代码再排查环境，那真是欲哭无泪。

3.5 常见环境问题排查

这部分我很想多说几句。因为这些坑，我自己都一个个踩过。下面几个问题，我敢说你在团队中一定会遇到。

问题1：依赖下载慢或失败

现象：mvn install 卡在某个包上，最后报网络超时。

原因：默认仓库在国外，你懂的。

解决：在 settings.xml 里配置阿里云镜像。


<mirror>
    <id>aliyunmaven</id>
    <mirrorOf>central</mirrorOf>
    <name>阿里云公共仓库</name>
    <url>https://maven.aliyun.com/repository/public</url>
</mirror>

问题2：NoSuchMethodError 或 ClassNotFoundException

现象：运行Demo时报错，提示找不到某个方法。

原因：通常是依赖版本冲突。比如你引入了A包，它依赖B包的1.0版本，但你的项目里引了B包的2.0版本，正好删了某个方法。

解决：用 mvn dependency:tree 查看依赖树，找到冲突的包，用 <exclusion> 排除掉。

    我的经验：我曾经在一个微服务项目里遇到过SLF4J的版本冲突，日志全部打不出来，排查了整整一下午才找到问题。后来我养成了一个习惯：引入任何第三方依赖，都先跑一遍 mvn dependency:tree。

问题3：IDEA 中提示“Unable to import Maven project”

现象：IDEA右侧Maven面板报红，无法重新加载。

原因：可能是IDEA的Maven版本与本地版本不匹配，或者本地 .m2 目录损坏。

解决：先检查IDEA中Maven配置的路径是否指向本地安装的Maven。然后试着删除 ~/.m2/repository 里对应的包，让IDEA重新下载。

问题4：Python脚本报SSL错误

现象：运行 pip install -r requirements.txt 时卡住或报错。

原因：同样，访问官方源超时。我们需要换成国内源，比如清华源。


pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

嗯，这里还要注意，有些公司内网环境下，需要配置代理。如果不配代理，SDK内置的Python上报模块也会连不上服务器。

最后，我再絮叨一句。环境配置看似琐碎，但真的值得花半小时仔细核对。我在团队里定了个规矩：每个成员在开始写代码前，先跑通一个最小的Demo，然后跟我说一声“环境通了”。这比后面花两天排查环境问题划算得多。