📚 课程目录第4章环境准备与安装

4. 环境准备与安装

好了，这一章我们来把开发环境搭起来。说白了就是——让我们的代码能用上列级加密SDK，而且跑得稳。我在好几个项目里都发现，环境装得顺不顺，直接决定了后面调试的心情。所以咱们一步步来，别着急。

4.1 支持平台一览

SDK目前官方支持两个生态：Java 11+ 和 Python 3.8+。为什么定这个门槛？

Java 11+：LTS版本，模块化、新加密API都稳定。我见过还在用Java 8的项目，结果遇到列加密库里用了`javax.crypto`的新特性，不得不升级——嗯，早升早省心。
Python 3.8+：3.6已经EOL了，3.8引入了`cryptography`包的一些关键接口，所以门槛卡在这儿。

如果你还在用Java 8或者Python 3.6，建议先升级，否则后面编译会报奇奇怪怪的方法找不到错误。

踩坑预警： 我遇到过团队里有人用Java 8强行跑Java 11编译的SDK jar，运行时报UnsupportedClassVersionError。这不是SDK的问题，是JVM版本不匹配。记住：编译环境和运行环境都要>=11。

4.2 Java SDK 安装：Maven vs Gradle

4.2.1 Maven 方式

我个人习惯用Maven，因为它依赖声明清晰，而且咱这SDK也提供了POM snippet。在你的pom.xml里加入：

<dependency>
    <groupId>com.example</groupId>
    <artifactId>column-encryption-sdk</artifactId>
    <version>2.1.0</version>
</dependency>

然后mvn clean install，Maven会自动拉所有依赖。记得指定<repository>吗？如果SDK发布在私有仓库，需要额外配置。我以前搞过一次，忘了加私有仓库的镜像，愣是下了半天只报404……后来加了个<distributionManagement>才搞定。

4.2.2 Gradle 方式

如果你团队用Gradle，也没问题。在build.gradle里写：

implementation 'com.example:column-encryption-sdk:2.1.0'

你想想看，Gradle的写法更短，但要注意它是用implementation还是api。我建议用implementation，避免把SDK的内部依赖泄漏出去。

小提示： 无论Maven还是Gradle，第一次下载依赖时务必开代理或VPN（如果SDK在海外仓库）。我曾经掉进过“下载一半超时导致jar损坏”的坑——校验和不过，重新mvn dependency:purge-local-repository才解决。

4.3 Python SDK 安装：pip 与虚拟环境

Python下就更直接了。一条命令：

pip install column-encryption-sdk

但听我一句劝：别直接在系统Python环境里装。一定要用虚拟环境。你想想看，多个项目不同版本的依赖打架，最后你都不知道哪个版本才是对的。我一般这样做：

创建虚拟环境：python -m venv venv
激活：source venv/bin/activate（Windows用venv\Scripts\activate）
安装：pip install column-encryption-sdk
验证：pip show column-encryption-sdk

为什么强调Python 3.8+？因为SDK内部用了dataclasses和cryptography的3.8+特性。你觉得低版本也能跑？我曾经试过Python 3.7，结果from __future__ import annotations都救不了，直接炸SyntaxError。

4.4 依赖冲突解决——这个坑我踩过好几次

环境装好了，一运行，报NoSuchMethodError或者ClassNotFoundException？大概率是依赖冲突。说白了，就是你的项目里同一个jar引了不同版本。

  常见场景： SDK依赖了com.google.guava:guava:30.0，你项目里另一个库引了guava:23.0。结果SDK调用某个新API时，类加载器拉到了旧版本——炸。

4.4.1 Java 依赖冲突解决三板斧

方法	做法	适用场景
exclude 传递依赖	在Maven的`<exclusions>`里去掉冲突项	你知道具体哪个传递依赖有问题
版本锁定（dependencyManagement）	在`<dependencyManagement>`里强制指定版本	你希望统一整个项目的版本
Shade 插件	用Maven Shade Plugin把SDK的依赖“阴蔽”到自己的命名空间	依赖冲突太复杂，或者第三方库不能改

举个例子。记得有一次，我在微服务里引入列加密SDK，结果和Spring Boot的logback冲突。我直接用<dependencyManagement>锁定guava版本为30.0，所有模块统一，再也没报错。

Gradle下更方便：

implementation('com.example:column-encryption-sdk:2.1.0') {
    exclude group: 'com.google.guava', module: 'guava'
}
// 然后自己声明你需要版本
implementation 'com.google.guava:guava:30.0-jre'

4.4.2 Python 依赖冲突的解法

Python下没有Maven那么精细的树，但可以用pip check快速发现不一致的依赖。另外，我建议在项目里用requirements.txt锁定版本，配合pip-tools里的pip-compile来生成兼容的版本列表。

如果实在冲突得厉害，可以考虑用pip install --no-deps安装SDK，自己手动补它需要的依赖。但这样做有点累，我一般只在快速验证时才用。

特别注意： Python的列加密SDK依赖cryptography库，而cryptography又依赖OpenSSL。如果你在macOS上用Homebrew装的不兼容，会报错。解决办法：先brew reinstall openssl@1.1，再pip install。

4.5 验证安装——跑一个最小例子

环境装好了，我们得确认SDK真正能用。写一个最简单的列加密调用：

Java 示例：

import com.example.ColumnEncryptor;

public class Test {
    public static void main(String[] args) {
        ColumnEncryptor enc = new ColumnEncryptor();
        String plain = "敏感数据";
        String encrypted = enc.encrypt(plain);
        System.out.println("加密结果: " + encrypted);
        System.out.println("解密结果: " + enc.decrypt(encrypted));
    }
}

Python 示例：

from column_encryption_sdk import ColumnEncryptor

enc = ColumnEncryptor()
plain = "敏感数据"
encrypted = enc.encrypt(plain)
print("加密结果:", encrypted)
print("解密结果:", enc.decrypt(encrypted))

如果能正常输出加密和解密后的内容，说明环境OK。如果报ModuleNotFoundError或ClassNotFoundException，那就回头看依赖冲突那部分。

下面这张图把整个环境准备流程串了一遍，你可以对照着检查自己的步骤。

好了，环境准备到这里就齐全了。接下来你可以放心写业务代码，不会再被那些诡异的ClassNotFound折磨。如果你装的过程中遇到其他问题，回头看看上面的表格和流程图，多半能找到原因。