JNA写了三篇前面把基础映射和回调都聊得差不多了这篇单刀直入聊最让人头疼的引用传递。很多从JNI转过来的人或者刚开始用JNA查资料的人第一次看到ByReference这个后缀都会愣一下Java里明明全是引用传递为什么到了JNA反而要专门搞一个Reference类答案很简单Java的“引用”和C的“指针”根本不是一回事。Java方法里改形参实参不会变但C函数签名里但凡带个*就意味着这个参数可能是输出值、可能要改调用方的变量、可能要返回一块内存地址。要在JNA里替Java搞定这件事就得靠ByReference这一族类。这篇是系列第三篇专门把引用传递的机制、选型、踩坑一次讲清。1. 理解引用传递为什么绕不开ByReference1.1 Java与C的参数传递差异先看一个最朴素的问题同样是写代码为什么Java那边调用C库就绕不过引用传递Java的方法参数传递严格来说是值传递。传入对象的时候传的是对象引用的副本你在方法内部对这个引用重新赋值外面的变量根本不知道。很多人说“Java对象就是引用传递”这是不严谨的——对象本身是共享的但“引用变量”的传递仍然是值语义。C语言不一样。函数签名里出现int *p、char **s、struct Foo *out都意味着调用方和函数共享同一块内存。函数内部写*p 100调用方拿到的变量立刻变成100。这种“通过指针直接改调用方变量”的能力就是所谓的引用传递。JNA要做的事情是用Java类型去模拟这种C语义。你不可能在Java里把int变量地址直接交出去JVM不允许、也不安全于是JNA搞了一个折中方案用一个Java对象包装一块原生内存的地址把这个对象传给C函数C函数写的是它背后那块内存调用结束后你再从对象里把值读出来。这个包装对象就是ByReference。1.2 JNA的三种传参形态JNA调用原生函数时参数大体上有三种表现形态。第一种是最简单的值传递。C函数签名是int foo(int x)Java声明就是int foo(int x)两边都是普通值。这种没有任何悬念传入多少就是多少。第二种是数组或缓冲区。C函数签名是void fill(char *buf, int size)Java声明可以用byte[]对应。JNA会把数组的首地址传给CC往数组里写数据Java侧在调用返回后直接读取同一个数组。这种方式适合“事先知道缓冲区大小”的固定空间场景。第三种就是真正的指针引用对应C函数签名里的int *、long *、void **等等。Java侧没有天然的“指向变量的指针”所以JNA提供了IntByReference、LongByReference、PointerByReference这些类。你用new IntByReference(0)创建一个对象把它传给C函数C函数往这个对象背后的内存里写值调用结束后通过getValue()拿结果。这三种形态里数组和引用类都算“广义引用传递”但语义上有本质区别数组是你预先分配好空间让C去填ByReference则是在调用前由JNA分配一小块原生内存C去写你再去读。很多初学者把两者混用比如用IntByReference处理本可以用int[]解决的参数或者反过来用数组去接C函数动态分配的内存结果要么取不到值要么内存管理一地鸡毛。1.3 ByReference的底层工作原理ByReference本身是一个抽象类它继承自Pointer本质上就是一个“带类型信息的指针对象”。每个具体的子类比如IntByReference内部持有一块原生内存这块内存的大小恰好能容纳一个int。当JNA把这些对象传到原生函数那边时传入的是这块内存的地址。C函数拿到的就是一个货真价实的int *指针可以随意读写。调用结束后你调用getValue()JNA从这块内存里读出当前值转成Java类型还给你。这里面有个很重要的点这块内存的分配和释放是JNA在调用过程中自动管理的。正常情况下你不用担心IntByReference背后那块原生内存泄漏JNA会在合适的时机清理。但注意如果C函数把这个指针保存下来留到以后继续用那JNA就管不了了——这就涉及生命周期问题后面常见问题里细说。提示ByReference是抽象类你不能直接new ByReference()但PointerByReference等子类都是可以直接实例化的。2. ByReference家族速查与选型2.1 内置引用类型对照表JNA针对Java基本类型都提供了对应的引用类。把这些类背下来等于拿到一张速查表。Java 基本类型JNA 引用类对应 C 类型典型用途intIntByReferenceint *错误码、状态值、计数器longLongByReferencelong long * / int64_t *大数值输出、累积量doubleDoubleByReferencedouble *浮点结果、比率floatFloatByReferencefloat *浮点结果shortShortByReferenceshort *短整型输出byteByteByReferencechar *单字节单字符输出boolean一般不用引用类int * / BOOL *状态标志PointerPointerByReferencevoid **动态内存、字符串指针、句柄NativeLongNativeLongByReferencelong *平台相关平台原生 longSizeTSizeTByReferencesize_t *长度、容量有两个最常用的必须提一下PointerByReference和NativeLongByReference。PointerByReference对应的是void **也就是“指向指针的指针”。C语言里要返回一块动态分配的内存典型写法是void **outPtr函数内部*outPtr malloc(...)或者*outPtr some_existing_buffer。Java侧用PointerByReference接调用后getValue()拿到一个Pointer再通过Pointer的API读取数据。这个类在字符串输出、内存块输出、句柄获取三个场景里几乎是标配。NativeLongByReference则是专门处理平台差异的。C标准里long在Windows 64位下是4字节在Linux 64位下是8字节。如果你直接映射成Java的long在Windows上会出问题。JNA的NativeLong会跟着平台自适应对应的NativeLongByReference自然也是安全的选择。2.2 从C签名到Java声明一段对照详解纸上谈兵没意思直接看例子。假设C侧有个函数int compute_stats(double *mean, double *stddev, int *count);函数内部会往mean、stddev、count这三个指针指向的地址里写值返回值是int型的调用状态。Java侧接口声明public interface StatsLibrary extends Library { StatsLibrary INSTANCE Native.load(mystats, StatsLibrary.class); int compute_stats(DoubleByReference mean, DoubleByReference stddev, IntByReference count); }调用代码DoubleByReference meanRef new DoubleByReference(0); DoubleByReference stddevRef new DoubleByReference(0); IntByReference countRef new IntByReference(0); int status StatsLibrary.INSTANCE.compute_stats(meanRef, stddevRef, countRef); if (status 0) { double mean meanRef.getValue(); double stddev stddevRef.getValue(); int count countRef.getValue(); }这个模式再明显不过创建引用对象 → 传入 → 调用 →getValue()。参数个数再多套路也一样。你可以把getValue()之后的操作想象成从一块共享白板上把别人替你写好的公式抄走。还有一种常见写法是C侧把引用参数当输入输出参数用既读又写。比如void add_to_total(long *total, long delta);这里total既是输入也是输出。Java声明里依然用NativeLongByReference初始化时把初始值放进去NativeLongByReference total new NativeLongByReference(new NativeLong(100)); library.add_to_total(total, new NativeLong(50)); long result total.getValue().longValue();注意初始化用的是NativeLong对象而不是直接传long。这和LongByReference不一样后者可以直接传long。如果搞混编译期就会发现类型不匹配。2.3 自定义ByReference什么时候需要JNA提供了一套内置引用类但实际项目里难免遇到自定义类型。最典型的场景是C侧定义了一个typedef比如typedef void *HANDLE; void open_device(HANDLE *handle);理论上HANDLE *就是void **用PointerByReference完全能搞定。但如果你想让代码更语义化或者想在getId时自动做类型转换可以自己定义一个类继承ByReferencepublic class HandleByReference extends ByReference { public HandleByReference() { super(Pointer.SIZE); // 分配一个指针大小的内存 } public void setValue(Pointer value) { getPointer().setPointer(0, value); } public Pointer getValue() { return getPointer().getPointer(0); } }这里super(Pointer.SIZE)是关键——你得告诉JNA要为这个引用类型分配多少字节原生内存。对于指针类型的引用就是Pointer.SIZE在32位平台上通常是464位平台是8。自定义ByReference还有一个经典用途某个C函数的参数是指针数组比如char **argv你觉得PointerByReference读起来不够直观也可以继承ByReference在里面封装getStringArray()方法。不过一般建议能用内置类别过度设计自定义类只在复用率高、或者确实需要封装额外行为的时候才动手。3. 实战模拟一个底层算法库的Java绑定3.1 C侧原型一个混搭引用参数的接口为了让引用传递的各个细节落到实处我模拟一个底层图像算法库的C接口。这个库处理某种点云数据函数是typedef struct { int width; int height; } FRAME_INFO; int pointcloud_process(const char *inputPath, FRAME_INFO *frameInfo, float **points, int *pointCount, char **message);先拆解一下这个C函数inputPath输入参数传入一个字符串路径Java侧用String映射。frameInfo这是一个结构体指针既是输出参数C函数会往里面填宽高信息。pointsfloat **典型的一级指针传地址。C函数内部会动态分配一块float数组把首地址写到*points里。pointCountint *输出点个数。messagechar **函数内部会赋值一个错误或状态消息可能指向静态字符串也可能指向动态分配的缓冲区。这个函数综合了结构体指针、指向指针的指针、标量指针几乎把引用传递常见的坑都覆盖了。Java侧接口声明长这样public interface PointCloudLib extends Library { PointCloudLib INSTANCE Native.load(pointcloud, PointCloudLib.class); int pointcloud_process(String inputPath, FRAME_INFO.ByReference frameInfo, PointerByReference points, IntByReference pointCount, PointerByReference message); }3.2 结构体参数的ByReference声明在JNA里结构体参数有两种映射方式按值传递用Structure本身按指针传递用Structure.ByReference。C函数签名里FRAME_INFO *frameInfo是标准指针对应Java侧应该用FRAME_INFO.ByReference。结构体定义public class FRAME_INFO extends Structure { public int width; public int height; public FRAME_INFO() { super(); } Override protected ListString getFieldOrder() { return Arrays.asList(width, height); } public static class ByReference extends FRAME_INFO implements Structure.ByReference { } }Structure.ByReference是一个标记接口它不增加任何方法只告诉JNA这个类的实例在传给原生函数时要传递结构体的指针地址而不是整个结构体的拷贝。调用时FRAME_INFO.ByReference frameInfo new FRAME_INFO.ByReference(); frameInfo.width 0; frameInfo.height 0;其实就算不初始化字段也没关系反正C函数会往里面写值。不过显式置0能让代码意图更清楚。3.3 调用后的值读取与内存处理完整调用代码PointerByReference pointsRef new PointerByReference(); IntByReference countRef new IntByReference(0); PointerByReference messageRef new PointerByReference(); FRAME_INFO.ByReference frameInfo new FRAME_INFO.ByReference(); int status PointCloudLib.INSTANCE.pointcloud_process( C:/data/scan_001.xyz, frameInfo, pointsRef, countRef, messageRef); if (status ! 0) { // 错误时C库通常会在message里给出原因 Pointer msgPtr messageRef.getValue(); String errorMsg msgPtr ! null ? msgPtr.getString(0, UTF-8) : ; throw new RuntimeException(调用失败错误码 status 消息 errorMsg); } int width frameInfo.width; int height frameInfo.height; int count countRef.getValue(); Pointer pointPtr pointsRef.getValue(); // 读取动态数组 float[] pointData pointPtr.getFloatArray(0, count * 3); // 假设是xyz三元组这里有几个容易忽略的细节。pointsRef.getValue()返回的是一个Pointer对应C侧动态分配的float数组。你要读数组里的值必须知道元素个数——所以这里才配套一个pointCount引用参数。这是C接口设计里非常常见的组合T** int*指针加长度缺一不可。getFloatArray(0, count * 3)里的0表示从偏移量0开始读count * 3表示读多少个float。如果C函数保证points数组长度至少是count * 3每个点有三个坐标值这个读法就是对的。内存这块必须注意这个points指针是C侧用malloc或类似手段分配的JNA压根不知道它的存在所以JNA不会帮你释放。用完以后如果有对应的释放函数必须自己调用。比如C库配套一个pointcloud_free(float *points)Java侧也要声明并调用public interface PointCloudLib extends Library { // ... void pointcloud_free(float *points); }等等JNA的接口声明里是不能直接写指针星号的这里只是我为了示意C侧逻辑。正确声明应该是void pointcloud_free(Pointer points);调用PointCloudLib.INSTANCE.pointcloud_free(pointPtr);这个“谁分配谁释放”的原则是引用传递里最容易出事的点后面第4章专门展开。3.4 通过Pointer读取字符串和结构化数据message参数是char **典型双指针。C函数内部可能是这样实现的char errorBuffer[256]; snprintf(errorBuffer, sizeof(errorBuffer), file not found: %s, inputPath); *message errorBuffer;也可能是*message success;前者指向栈缓冲区后者指向字符串常量。不管哪种Java侧用PointerByReference接都不会有问题因为JNA只关心读出来的Pointer指向的内容不关心里面存的是哪来的字符串。读取方式String message messageRef.getValue().getString(0, UTF-8);有个坑是如果C函数在某些分支里忘记给*message赋值那getValue()可能返回null。所以读取前最好判空或者把Pointer先存到局部变量里再处理不要写一长串链式调用。frameInfo这种结构体指针读取就更直接了调用返回后frameInfo.width和frameInfo.height字段会自动同步。原理是JNA在调用前后会把结构体的原生内存内容同步回Java对象字段。这也是Structure.ByReference比Pointer更推荐的原因——你不需要手动算偏移量、不需要调getInt直接用字段名就行。4. 常见问题与避坑清单4.1 误区把函数返回值当成指针输出这是我见过最多、也最难排查的一类问题。有些C函数会直接把动态内存的首地址作为返回值返回比如char *get_error_message(int code);乍一看Java侧直接声明成String get_error_message(int code)好像也没问题JNA确实会自动转换返回的char*为String。但这种写法的风险在于如果返回的指针是C侧malloc分配的内存而接口声明成StringJNA会帮你做转换但不会帮你释放。更糟的是如果函数返回的是指向内部静态缓冲区的指针JNA转换完就完事也不会有问题。麻烦的地方在于你不知道到底哪种情况一旦内存需要释放你没有拿到原始指针想释放都无从下手。更稳妥的写法是声明成Pointer get_error_message(int code)自己手动转字符串、自己手动管理生命周期。如果确定不需要释放再考虑直接声明成String。反过来还有一种情景C函数签名是void get_name(char **name)你得用PointerByReference但有人想偷懒声明成String get_name()这是完全错误的——函数根本没有返回值你声明成有返回值JNA会从垃圾内存里读一块当作指针转字符串轻则乱码重则崩溃。4.2 指针有效性与内存归属问题引用传递完后你拿到一个Pointer但这个指针指向的内存能活多久完全取决于C侧的定义。如果指针指向的内存是C函数自己分配并管理的静态区那么它通常在整个程序生命周期内有效。如果它指向的是函数内部的栈缓冲区函数返回后这块内存就悬空了你再访问就是典型的悬垂指针。这种问题用Java的思维是理解不了的因为Java根本没有“栈上对象”这个概念但对C来说这是家常便饭。最典型的例子就是char *get_version() { char buf[100]; sprintf(buf, v%d.%d, major, minor); return buf; // 大错特错buf是栈内存 }这类问题一旦通过JNA暴露出来具体现象很随机有时候能读出正常字符串有时候乱码有时候直接抛Invalid memory access。排查的方式只有一个在C侧确认指针的生命周期不能在Java这边瞎猜。JNA官方文档和常见开源项目里的共识是Java侧只负责释放JNA自己分配的Memory对象或者C库明确要求调用方释放的内存。至于C库内部自己的缓冲区Java侧不该也不能去动。4.3 long的位数陷阱用LongByReference并不总是安全的除非你非常确定C侧的long就是64位。C标准里long的长度是平台相关的。Windows 64位是4字节LLP64模型Linux 64位是8字节LP64模型。同一个库同一份代码在Windows上编译出来的long是4字节在Linux上编译出来是8字节。Java的long是固定的64位8字节直接对应C的int64_t但并不总是对应C的long。所以处理C的long *参数时优先考虑NativeLongByReference。这个类会根据当前运行平台自动选择正确的宽度。我在多个跨平台项目里吃过这个亏Windows上跑得好好的部署到Linux后数值突然不对了最后定位到就是long宽度不同导致JNA读取位置偏移。简单记一下Cint *Java用IntByReference稳妥。Clong long */int64_t *Java用LongByReference因为两边都是64位。Clong *Java用NativeLongByReference最保险。Csize_t *Java用SizeTByReference别自作主张映射成LongByReference在32位平台上又是一轮坑。4.4 调试技巧与性能建议引用传递的调试难点在于你永远无法直接看到C函数到底往指针里写了什么。我的排查路径通常是三层第一层检查getValue()前后的值。如果调用后值没变先怀疑C函数压根没走到写指针的分支比如参数校验失败提前返回了。第二层检查C函数的返回值。很多C函数通过返回值报告执行状态不要只盯着引用参数有没有值。异常路径下引用参数可能保持原始值也可能被写入错误信息这两种情况都要考虑到。第三层实在不行就在C侧加日志或者用一个简单的测试用例单独调这个函数把其他参数都固定住看哪个引用参数没被正确写入。这个方法笨但确实有效。性能方面new IntByReference()之类的小对象开销其实很低正常业务代码随便用。但如果是在高频循环里调用比如一秒钟上万次每次都在循环内部创建新的引用对象JVM的GC压力和JNA框架的映射开销就会被放大。这时候可以复用引用对象把ByReference实例声明在循环外IntByReference count new IntByReference(0); for (int i 0; i 100000; i) { count.setValue(0); lib.some_call(count); int value count.getValue(); }复用前记得重新setValue初始化否则上一次调用的残留值会混进来。另外如果引用对象持有的是大块内存的指针比如PointerByReference里面存放了C侧分配的几百MB缓冲区的地址那么读完后置空这个引用对象、并尽快调用C侧释放函数能显著降低内存压力。调试JNA还有一个很实用的小技巧在启动参数里加-Djna.debug_loadtrue和-Djna.dump_memorytrue。前者可以看JNA加载原生库的详细日志后者会在调用时输出内存布局。不过dump_memory输出非常冗长只建议在小函数上临时开。最后分享一个我自己的小习惯凡是涉及引用传递的Java方法我都在代码里写明它对应的C原始签名作为注释。比如// C: int pointcloud_process(const char *, FRAME_INFO *, float **, int *, char **) int pointcloud_process(String inputPath, FRAME_INFO.ByReference frameInfo, PointerByReference points, IntByReference pointCount, PointerByReference message);这么做的好处是三个月后回来看代码不用去翻头文件一眼就能对上参数类型。而且如果C侧接口做了不兼容修改测试编译期或者第一次调用时就能立刻发现映射错位。很多人觉得JNA写起来轻松就忽视了这层文档等到参数多了、指针套指针的时候没有原始签名对照排查问题就跟闭着眼睛找路一样难受。这些年用JNA写了大量和C库对接的绑定层我的体会是引用传递本身并不复杂复杂的是它的生命周期和平台差异。把ByReference当成“JNA帮你托管的一块原生内存的代理”把getValue()当成“从共享内存抄结果”把PointerByReference当成“C函数返回地址的接收器”整个模型就清晰了。遇到内存诡异问题先别急着怀疑JNA回到C侧把指针来源和生命周期捋一遍八成问题都在那里。