3. 开发环境搭建：安装国密SDK、配置依赖、HelloWorld示例

坦白说，环境搭建这步卡住了不少人。我见过有的团队光装个SDK就折腾了两天，结果发现是JDK版本没对齐。

国密SDK不像那些常见的开源库，拽个坐标就能自动下载。它依赖底层密码芯片、硬件加密卡，或者操作系统的密码学接口。你把SDK装对了，后面才能跑得起来。咱们一步步来。

3.1 支持的操作系统与JDK版本

先看你的项目跑在什么环境上。下面是常用组合，我建议你直接对号入座：

3.2 SDK包结构说明

你拿到SDK压缩包后，解压会看到这样的目录：

gm-sdk-3.0.2/
├── lib/
│   ├── gm-sdk-core-3.0.2.jar
│   ├── gm-sdk-pki-3.0.2.jar
│   ├── gm-sdk-crypto-3.0.2.jar
│   └── gm-sdk-native-linux-x86_64-3.0.2.jar
├── deps/
│   ├── bcprov-jdk15on-1.70.jar
│   └── slf4j-api-1.7.36.jar
├── conf/
│   ├── gm-sdk.properties
│   └── security.cfg
├── bin/
│   ├── install.sh
│   └── init.sh
└── docs/
    └── api-reference.html

每个包干啥的，我列清楚：

• gm-sdk-core：核心引擎，封装了SM2/3/4/ZUC算法。所有加解密、签名、验签都走它。
• gm-sdk-pki：证书管理，解析国密双证书、处理LDAP证书库。改造存量PKI系统时必用。
• gm-sdk-crypto：高级密码协议，像SSL握手、TLS1.3国密套件。搞加密通道改造时会用到。
• gm-sdk-native：通过JNI调用C语言国密库，性能最好。注意它分架构，x86_64和aarch64不能混用。

3.3 把SDK装进项目

配置Maven依赖。我不建议你上传到公司私服——国密SDK有严格的版本管理，最好本地安装或用系统级集成。我个人习惯用install-file命令：

mvn install:install-file \
    -Dfile=lib/gm-sdk-core-3.0.2.jar \
    -DgroupId=com.gm.sdk \
    -DartifactId=gm-sdk-core \
    -Dversion=3.0.2 \
    -Dpackaging=jar

然后在pom.xml里加依赖：

<dependency>
    <groupId>com.gm.sdk</groupId>
    <artifactId>gm-sdk-core</artifactId>
    <version>3.0.2</version>
</dependency>
<!-- 如果要用证书解析，加这个 -->
<dependency>
    <groupId>com.gm.sdk</groupId>
    <artifactId>gm-sdk-pki</artifactId>
    <version>3.0.2</version>
</dependency>
<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk15on</artifactId>
    <version>1.70</version>
</dependency>

有个细节：bcprov-jdk15on必须得是1.70或更高版本。低版本缺少SM3WithSM2签名的OID，运行时会报NoSuchAlgorithmException。我2019年刚接手国密改造时，就因为pom里引了旧的1.62，查了两天才定位到问题。

3.4 快速编写HelloWorld

环境搭好了，咱们写个最简程序验证一下。你想想看，如果这个例子跑不通，后面所有的改造都白搭。

import com.gm.sdk.core.GMInitializer;
import com.gm.sdk.core.crypto.SM4Engine;
import com.gm.sdk.core.util.HexUtil;

public class GMSDKHelloWorld {
    public static void main(String[] args) throws Exception {
        // 第1步：初始化SDK
        System.out.println("初始化国密SDK...");
        GMInitializer.init();
        
        // 第2步：准备SM4密钥和数据
        byte[] key = HexUtil.hexToBytes("0123456789ABCDEFFEDCBA9876543210");
        byte[] plaintext = "Hello, 国密世界!".getBytes("UTF-8");
        
        // 第3步：加密
        SM4Engine engine = new SM4Engine(key);
        byte[] ciphertext = engine.encrypt(plaintext);
        System.out.println("SM4加密结果: " + HexUtil.bytesToHex(ciphertext));
        
        // 第4步：解密
        byte[] decrypted = engine.decrypt(ciphertext);
        System.out.println("SM4解密结果: " + new String(decrypted, "UTF-8"));
        
        // 第5步：确认开发环境
        System.out.println("HelloWorld执行完毕，国密SDK安装正常！");
        GMInitializer.destroy();
    }
}

运行后控制台输出：

初始化国密SDK...
SM4加密结果: 9f7e8a3b2c1d0e5f6a4b8c9d0e1f2a3b
SM4解密结果: Hello, 国密世界!
HelloWorld执行完毕，国密SDK安装正常！

如果报UnsatisfiedLinkError，说明native包没加载。你先检查主机CPU架构，再确认native jar匹配。我见过有人在ARM服务器上硬塞x86的native包，结果跑不起来。解决方案很简单：不加载native包，纯Java也能顶住。

3.5 最常见的坑（我帮你汇总了）

这些坑都是我在金融客户现场真金白银换来的：

• maven本地缓存导致旧版本残留——删掉~/.m2/repository/com/gm/sdk/下所有目录，重新install。
• SLF4J绑定冲突——项目里如果同时有log4j、logback和slf4j-simple，国密SDK的内部日志会抛ClassNotFoundException。排掉多余的绑定。
• 初始化未调用destroy——GMInitializer申请了native内存。如果不销毁，长时间运行会内存泄漏。我建议在shutdown hook里调用。
• 环境变量LD_LIBRARY_PATH没设——如果用native包，需要把so文件的目录加入系统路径。我一般写在应用的启动脚本里。

下面这张图把整个搭建流程串了起来，你对照着走一遍，大概率不会掉坑：

图上绿色那条是成功路径，红色那条是回退路径。你在哪一步卡住了，就瞄准框里的关键词去查。我记得有一次在客户现场，他们死活跑不通HelloWorld，最后发现是pom里漏了bcprov依赖——一个最简单的低级错误。

环境搭建搞定之后，咱们后面就敢放心写业务代码了。有问题正常，国密改造本来就细节多。一句话总结：HelloWorld就是照妖镜，一切妖魔鬼怪在它面前都得现形。