📚 课程目录第4章 JNI基础

第4章：JNI基础——Java Native Interface的工作原理与开发流程

说起JNI，很多人第一反应就是“麻烦”、“容易崩”。确实，JNI是Java和C/C++之间的一座独木桥，走好了能大幅扩展能力边界，走不好就是段错误和内存泄漏满天飞。我这些年做国密SDK多语言适配，打交道最多的就是这层桥接代码。说白了，JNI就是个中间人，帮JVM跟本地代码打招呼。

4.1 JNI到底干了什么

我们先拆开看看JNI的工作原理。JVM本身是C++写的，它知道怎么管理Java堆，怎么处理线程。但Java代码想调用本地库里的函数时，就需要一个翻译官。JNI就是这个翻译官。

当一个Java线程调用native方法时，会发生这几件事：

栈帧切换：JVM从Java栈切到native栈。我个人习惯把这种切换看作“换个跑道”，Java栈和native栈是独立的，数据不能直接互相引用。
参数映射：Java的基本类型（int, long等）直接映射成C语言的基本类型。引用类型（String, 数组, 对象）则转成jstring、jobjectArray、jobject等JNI专属类型。
方法定位：JVM通过函数名的编码规则（Java_包名_类名_方法名）找到对应的C函数。嗯，这里有个坑，符号修饰规则不同平台不一样，我们后面讲。
返回与同步：本地函数执行完后，结果再翻译回Java类型，切换回Java栈。如果涉及多线程，还得小心JNI的局部引用怎么管理。

为什么会这样设计？因为JVM根本不知道你的C代码里做了什么，C代码也不知道JVM内部的堆结构。双方只能通过JNI规范定义的接口函数互相通信。我在项目中遇到过很多次，直接在C里操作JVM内存，结果就是虚拟机直接挂掉。

Java类型	JNI类型	C语言表示	说明
int	jint	int32_t	直接映射，不做转换
long	jlong	int64_t	64位，注意字节对齐
String	jstring	jstring	不透明引用，需通过`GetStringUTFChars`访问
byte[]	jbyteArray	jbyteArray	数组也是不透明的，要用`GetByteArrayElements`
Object	jobject	jobject	所有Java对象的根类型，不能直接当作C结构体
Class	jclass	jclass	通过`FindClass`获取

关键认知：JNI不是让你绕开Java的管控，而是给了你一条受控的通道去跟本地世界对话。所有内存管理、类型转换、异常处理都得按JNI的规矩来。

4.2 开发流程拆解——从Java代码到本地库

开发一个JNI调用，大致分5步。我每次做国密算法的适配，都是按这个流程走，很少出岔子。

写Java native方法声明 在Java类里用native关键字声明方法，不加实现。比如：

public class Sm3Digest {
    // 计算SM3哈希值
    public native byte[] sm3Hash(byte[] input);
}

生成C头文件 用javac -h命令从编译后的.class文件生成C语言头文件。你会得到一个带长长的函数名的.h文件：

# 假设包名是 com.gm.sm3
javac -h . Sm3Digest.java
# 生成 com_gm_sm3_Sm3Digest.h

里面有个函数签名，像这样：

JNIEXPORT jbyteArray JNICALL 
Java_com_gm_sm3_Sm3Digest_sm3Hash(
    JNIEnv *env, 
    jobject thiz, 
    jbyteArray input);

实现C函数 编写对应的.c文件，实现SM3计算逻辑。这里要注意：env是指向JNI函数表的指针，所有操作都要通过它。我个人习惯先做个空壳测试，确认调用链通了再填实际算法。

JNIEXPORT jbyteArray JNICALL 
Java_com_gm_sm3_Sm3Digest_sm3Hash(
    JNIEnv* env, 
    jobject thiz, 
    jbyteArray input) {
    
    // 1. 获取输入字节数组的指针
    jbyte* inBytes = (*env)->GetByteArrayElements(env, input, NULL);
    jsize inLen = (*env)->GetArrayLength(env, input);
    
    // 2. 执行SM3计算（这里省略具体实现）
    unsigned char out[32];
    // sm3_hash(inBytes, inLen, out); // 简化的调用
    
    // 3. 创建输出数组并拷贝结果
    jbyteArray result = (*env)->NewByteArray(env, 32);
    (*env)->SetByteArrayRegion(env, result, 0, 32, (jbyte*)out);
    
    // 4. 释放输入数组的指针
    (*env)->ReleaseByteArrayElements(env, input, inBytes, JNI_ABORT);
    
    return result;
}

编译动态库 用gcc或Visual Studio把.c文件编译成.so（Linux）、.dylib（macOS）或.dll（Windows）。记得链接JNI的头文件目录（jni.h）。

gcc -shared -fPIC -I${JAVA_HOME}/include \
    -I${JAVA_HOME}/include/linux \
    -o libsm3native.so sm3_impl.c

加载并调用 在Java代码里用System.loadLibrary加载动态库，然后直接调native方法。

static {
    // 加载当前目录下的libsm3native.so
    System.loadLibrary("sm3native");
}

public static void main(String[] args) {
    Sm3Digest sm3 = new Sm3Digest();
    byte[] input = "hello".getBytes();
    byte[] hash = sm3.sm3Hash(input);
    // 打印结果...
}

我的习惯：在开发调试阶段，我不会在native方法里嵌复杂算法。先写个返回固定byte[]的桩函数，跑通整个JNI调用链路。确定Java端能正常调起来、不崩溃，再填充真实逻辑。这样可以快速定位问题是出在JNI调用本身还是算法实现上。

4.3 避坑清单——你可能已经踩过的雷

这部分我结合这些年的实战经验，列一份常见问题清单。我曾经在这上面栽过跟头，希望你看了能绕开。

符号名称不匹配 函数签名必须严格按Java_包名_类名_方法名的规则。包名里的点要换成下划线。如果包名里有_或$，还有额外的转义规则。我建议，生成头文件后，把函数签名直接复制到.c文件里，手写容易写错。
内存泄漏 通过GetStringUTFChars或GetByteArrayElements拿到的指针，用完后一定要调用对应的Release函数释放。否则JVM堆上的pin住的内存永远解不了，会导致GC出问题、堆外内存疯长。
局部引用溢出 JNI的局部引用表有容量限制（默认通常512个）。如果你在循环里频繁调用FindClass或NewString而不及时释放局部引用，会触发LocalRefOverflowError。解决办法是手动调用DeleteLocalRef，或者把循环体放到EnsureLocalCapacity保护区内。
异常处理错位 C代码里调用JNI函数（如FindClass）失败后，异常被挂起，但C代码不会自动抛异常。你得主动检查返回值，然后调用ExceptionOccurred判断，再手动ExceptionDescribe打印栈信息。不处理的话，后面再调用JNI函数就可能直接崩溃。
线程与JNIEnv JNIEnv是线程私有的，不能跨线程缓存使用。如果你想在另一个线程里调用JNI函数，必须通过AttachCurrentThread拿到该线程的JNIEnv。调用完再DetachCurrentThread。

重要警告：千万不要在C代码里直接修改Java对象的内部字段，除非你完全了解JVM的内存布局。正确的做法是用JNI提供的GetFieldID/SetField系列函数。我曾经见过同事直接拿jobject地址当作结构体指针用，结果虚拟机直接crash，当时查了一整天。

4.4 JNI与国密SDK适配的典型场景

做国密运算时，JNI调用有个突出的特点——频繁传递大型字节数组。SM2签名验签、SM3哈希、SM4加解密，输入输出动不动就是几十KB甚至几MB。这种情况下，如何在JNI层高效地处理字节数组直接决定了性能。

我记得有一次优化SM4的CBC加解密，原始实现每16字节调用一次GetByteArrayElements和ReleaseByteArrayElements，性能惨不忍睹。改成一次性把整个数据块的指针取出来，在C里循环做块加密，速度直接提高了30倍。

另外，Java端和C端的字节序是否一致也要确认。x86用little-endian，ARM默认也是little-endian，但某些网络协议或嵌入式设备可能是big-endian。SM2涉及大数运算，搞错字节序结果全错。

经验总结：国密SDK的JNI适配，核心就是两点——一是把JNI的数据传递开销降到最低，尽量一次传大块而不是多次传小块；二是严格管理内存，确保每对Get/Release都成对出现。做到这两条，你的native层就能跑得又快又稳。

看到这张流程图，你应该能对JNI调用的完整链路有个直观印象。Java端发起调用后，JNI层负责查找映射函数、转换参数类型，然后执行native实现，最后将结果沿着同样的路径回传。中间的每一个环节都可能出错——但反过来，只要你把控好数据类型映射、内存管理和异常这三个方面，JNI调用其实很稳定。