4、开发环境搭建：Java/Python环境配置，Maven/Gradle/Pip依赖管理

环境配置这件事，说难不难，说简单也真容易踩坑。我带过不少新人，十有八九第一周都卡在环境上。不是 JDK 版本不对，就是 Maven 拉不到依赖。

我个人习惯是「先跑通一个最小 demo，再去理解细节」。你想想看，要是连 Hello World 都跑不起来，后面加密算法、字段过滤这些都无从谈起。所以这一章，我就带你把 Java 和 Python 的开发环境彻底搞定。

4.1 Java 环境配置

4.1.1 JDK 版本选择

我们这个字段级加密 SDK 底层依赖 Java 的 javax.crypto 包，对 JDK 版本没有特别苛刻的要求。JDK 8 往上都行。但我建议你至少用 JDK 11。

为什么？JDK 8 虽然还能跑，但很多新工具链（比如最新的 Maven 和 Gradle 插件）已经逐步放弃对 JDK 8 的支持了。我曾经在一个老项目里强制用 JDK 8，结果某个加密库的 Security.getProviders() 行为在 JDK 8 和 JDK 11 上有细微差异，排查了两天才发现是 Provider 顺序的问题。所以，能用新就不用旧。

JDK 版本支持情况我的建议
JDK 8可用，但部分新插件不支持仅用于维护老项目
JDK 11 (LTS)主流，SDK 完整测试通过推荐首选
JDK 17+完全兼容，性能略有提升可选，需注意某些反射 API 限制
个人技巧：我习惯在 /opt/java 或 C:\Java 下按版本建目录，比如 jdk-11.0.21，这样切换版本时改 JAVA_HOME 就行，不用重新安装。

4.1.2 环境变量配置

这一步很简单，但最容易写错。说白了就是三个变量：

  • JAVA_HOME – 指向 JDK 根目录
  • PATH – 追加 %JAVA_HOME%\bin（Windows）或 $JAVA_HOME/bin（Linux/macOS）
  • CLASSPATH – 现代开发一般不需要手动设了，交给 Maven/Gradle 就好。

配置完后，打开终端运行 java -version 和 javac -version，两个命令都正常输出版本号才算成功。我见过有人只配了 java 没配 javac，结果编译报错还以为是 JDK 没装好。

4.2 Python 环境配置

Python 这边水更深一点——版本、虚拟环境、pip 源。我建议你统一用 Python 3.10 或 3.11，3.12 还太新，部分加密库（比如 pycryptodome）的 arm64 wheels 还没完全覆盖。

4.2.1 安装 Python

Windows 用户记住勾选「Add Python to PATH」。macOS 用户建议通过 brew install python@3.11 安装，系统自带的 Python 2 不要碰。Linux 用户用包管理器就好，但注意有些发行版（比如 Ubuntu）默认装的 python3 不带 pip，需要手动装 python3-pip。

4.2.2 虚拟环境工具

我强烈推荐 pyenv + virtualenv 的组合。pyenv 负责管理 Python 版本，virtualenv 负责隔离项目依赖。如果你用 PyCharm，它内置的 virtualenv 也很好用。不过我个人更喜欢 conda——尤其是做数据相关的项目时，conda 管理底层 C 库依赖更方便，但单纯做 SDK 开发用 venv 就够了。

# 创建虚拟环境
python3 -m venv venv

# 激活（Linux/macOS）
source venv/bin/activate

# 激活（Windows PowerShell）
.\venv\Scripts\Activate.ps1

# 退出
deactivate
注意：虚拟环境千万不要放进版本控制。我见过有人把 venv/ 目录提交到 Git 仓库，结果换个 macOS 就炸了。记得在 .gitignore 里加一行 venv/。

4.3 依赖管理工具对比与配置

Java 生态里 Maven 和 Gradle 两分天下，Python 这边基本是 pip 一统江湖。但三者背后的理念其实相通：声明依赖 → 解析冲突 → 下载到本地仓库 → 打包时引入。

特性MavenGradlePip
配置文件pom.xmlbuild.gradle / .ktsrequirements.txt
依赖来源Maven Central / 私有仓库Maven Central / Ivy / 自定义PyPI / 私有索引
依赖锁定maven-dependency-plugin 或 versions:display-dependency-updates天然支持 gradle.lockfilepip freeze > requirements.txt
构建速度慢（串行执行阶段）快（增量编译 + 并行）N/A（纯安装）
学习曲线XML 有点啰嗦，但规则简单Groovy/Kotlin DSL 灵活，但坑多极低，几行搞定

我的习惯是：团队项目用 Gradle，个人图书馆项目用 Maven。因为 Gradle 的增量编译在大型 SDK 里能省很多时间，但它的依赖缓存偶尔抽风，需要 --refresh-dependencies 强制刷新。

4.3.1 Maven 核心配置 (pom.xml)

我把加密 SDK 的 Maven 配置模板贴出来，你直接改 groupId 和 artifactId 就能用：

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>field-level-encryption-sdk</artifactId>
    <version>1.0.0</version>

    <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <!-- 加密核心库 -->
        <dependency>
            <groupId>com.github.javadev</groupId>
            <artifactId>encrypt-core</artifactId>
            <version>2.5.0</version>
        </dependency>
        <!-- 测试框架 -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>5.10.0</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>
小经验：Maven 的默认中央仓库在国外，第一次拉包可能很慢。你可以在 settings.xml 里配置阿里云镜像：https://maven.aliyun.com/repository/public。这个操作能救你不少时间。

4.3.2 Gradle 核心配置 (build.gradle)

如果你选 Gradle，配置更简洁，还能用 Kotlin DSL 写类型安全配置：

plugins {
    id 'java'
    id 'java-library'
}

group 'com.example'
version '1.0.0'

repositories {
    mavenCentral()
    // 可以加私有仓库
    // maven { url 'https://repo.mycompany.com/releases' }
}

dependencies {
    implementation 'com.github.javadev:encrypt-core:2.5.0'
    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'
}

test {
    useJUnitPlatform()
}

Gradle 的 Wrapper（gradlew）是团队协作的命门——记得把它也提交到 Git 仓库，这样所有人用的 Gradle 版本统一，不会出现「我本地能跑，你那就报错」的尴尬。

4.3.3 Pip 依赖管理 (requirements.txt)

Python 的依赖管理我一般这么处理：

# 生产依赖
pycryptodome==3.19.1
pydantic==2.5.0

# 开发/测试依赖
pytest==7.4.3
pytest-cov==4.1.0

安装时执行 pip install -r requirements.txt。如果你需要区分环境，可以拆成 requirements-base.txt 和 requirements-dev.txt，然后用 -r 引用。

嗯，这里要注意一点：pip freeze 会把所有间接依赖也打进去，导致文件膨胀。我一般只用 pip freeze 生成锁定文件，但手动维护的 requirements.txt 只写直接依赖，版本号加个 >= 下限更灵活。

4.4 依赖管理流程图

搞了这么多配置，你可能有点晕。我画了一张图，把三种工具的核心流程统一出来——说白了都是两步：声明 → 解析并下载。

依赖管理核心流程（Maven / Gradle / Pip 统一视图） ① 声明依赖 ② 解析依赖（含冲突检测） ③ 从仓库下载依赖 ④ 缓存到本地仓库 配置文件示例 Maven: pom.xml / Gradle: build.gradle Pip: requirements.txt 常见问题 • 版本冲突（依赖地狱） • 网络超时 / 镜像配置 • 缓存损坏（gradle --refresh） 总原则：声明 → 解析 → 下载 → 缓存，所有工具都跑这个循环

4.5 避坑指南（个人血泪史）

  • JDK 多版本切换：我曾经把 JAVA_HOME 配成了 C:\Program Files\Java\jdk-11\bin，实际上应该配到根目录。结果 java -version 正常，但 javac 报错，因为 javac 不在 bin 的子目录里。正确的路径是 C:\Program Files\Java\jdk-11，不带 \bin。
  • Gradle Daemon 内存溢出：如果你在低配笔记本上跑 Gradle，记得限制 Daemon 内存。在 ~/.gradle/gradle.properties 加一行 org.gradle.jvmargs=-Xmx512m，否则构建时 IDE 可能直接卡死。
  • pip 安装加密库失败：在 Windows 上装 pycryptodome 如果缺 VC++ 编译环境，直接去 PyPI 下载对应 Python 版本的 wheel 文件手动安装。别浪费时间装 Visual Studio，一个 wheel 文件解决所有问题。
  • Maven 私服认证：如果你公司有私有仓库，settings.xml 里不要明文写密码。用 maven-encrypt-plugin 加密，或者设环境变量 MAVEN_PASSWORD 在 CI/CD 流程里注入。

测试环境是否就绪：配置完所有环境后，我建议你先跑一个最小闭环测试——创建一个新的空项目，引入 SDK 核心依赖，写一个简单的加密/解密 main 方法，确保编译、测试、打包整个流程无报错。这一步能帮你筛掉 90% 的环境问题。

好啦，环境搭好了，依赖也拉下来了。下一步我们就可以写第一个字段级加密的 Demo 了。你先把本地环境跑通，回头遇到问题可以对照这张避坑清单排查。

← 上一章 📖 返回目录 下一章 →