本文深入探讨了使用JNA与原生库交互时，如何正确映射c语言中的复杂结构体（Struct）和联合体（union）。核心在于JNA要求所有代表C结构体或联合体的Java类都必须继承com.sun.jna.Structure或com.sun.jna.Union，并正确定义字段顺序。文章提供了两种解决方案：直接JNA映射和“友好”对象转换，并强调了内存管理、字段顺序和联合体处理等关键注意事项，旨在帮助开发者构建健壮的JNA集成。
JNA与原生数据类型映射概述
java native access (jna) 库为java应用程序提供了一种无需编写jni代码即可调用原生共享库（如dll、so文件）中函数的能力。其核心机制之一是将java对象映射到c语言的原生数据结构。当原生库的接口涉及复杂的结构体或联合体时，正确地进行映射至关重要。
问题场景分析：JNA对嵌套结构体的要求
在JNA中，任何需要在Java侧表示C语言结构体（struct）或联合体（union）的类，都必须继承自com.sun.jna.Structure或com.sun.jna.Union。这是JNA能够理解这些数据类型在原生内存中布局的关键。
考虑以下原生C语言结构体定义：
// C语言中的Install_CD97_GTML结构体 typedef struct { UCHAR ucProtocolType; UCHAR ucaddReader; } Install_CD97_GTML_Params; // 假设这是嵌套结构体的名称 // C语言中的InstallCardParam联合体 typedef union { Install_CD97_GTML_Params xCd97Param; // Install_CD98_GTML xCd98Param; // 示例：其他可能的联合体成员 // Install_CD99_GTML xCd99Param; } InstallCardParam; // C语言中的InstallCard结构体 typedef struct { eTypCardType xCardType; InstallCardParam iCardParam; // 包含一个联合体 } InstallCard; // 原生函数声明 short sSmartInstCardEx(const InstallCard *pxInstallCard);
我们来看两种Java映射方式及其结果。
场景一：扁平化结构映射（工作正常）
最初的尝试将ucProtocolType和ucAddReader直接放在Install_CD97_GTML类中，该类继承自InstallCard（而InstallCard继承自Structure）。这种方式之所以能够工作，是因为它实际上是创建了一个包含所有字段的扁平化结构，JNA能够正确解析其内存布局。
// InstallCard 继承自 Structure public class InstallCard extends Structure { public int xCardType; @Override protected List<String> getFieldOrder() { // 注意：这里定义了所有字段，包括子类中的字段，这在JNA中是可行的 // 但通常推荐子类自己定义其特有字段，并由父类通过其继承链管理 return Arrays.asList("xCardType", "ucProtocolType", "ucAddReader"); } } // Install_CD97_GTML 继承 InstallCard，直接包含参数字段 public class Install_CD97_GTML extends InstallCard { public byte ucProtocolType; public byte ucAddReader; // 构造函数等... } // 调用示例 Install_CD97_GTML pxInstallCardCD97 = new Install_CD97_GTML(); pxInstallCardCD97.xCardType = 1; pxInstallCardCD97.ucAddReader = 0; pxInstallCardCD97.ucProtocolType = 1; // res = ReaderThalesApi.INSTANCE.sSmartInstCardEx(pxInstallCardCD97); // 正常工作
这种方式虽然有效，但它并没有完全遵循C语言中嵌套结构体和联合体的原始设计，而是在Java层面将所有字段扁平化了。
场景二：引入非JNA Structure的嵌套类（导致错误）
当尝试引入一个独立的Java类CD97_GTML_Parameter来封装ucProtocolType和ucAddReader，并将其作为字段嵌套到Install_CD97_GTML中时，问题出现了：
// InstallCard 保持不变 public class InstallCard extends Structure { public int xCardType; @Override protected List<String> getFieldOrder() { // 注意：这里的getFieldOrder()可能需要调整以反映实际的结构 // 如果Install_CD97_GTML是InstallCard的子类，并且iCardParam是Install_CD97_GTML特有的字段 // 那么InstallCard的getFieldOrder()可能只包含它自己的字段 return Arrays.asList("xCardType"); } } // 引入一个普通的Java类，不继承Structure public class CD97_GTML_Parameter { public byte ucProtocolType; public byte ucAddReader; // 构造函数等... } // Install_CD97_GTML 继承 InstallCard，并包含非Structure类型的字段 public class Install_CD97_GTML extends InstallCard { public CD97_GTML_Parameter iCardParam; // 问题所在：CD97_GTML_Parameter不是Structure @Override protected List<String> getFieldOrder() { return Arrays.asList("xCardType", "iCardParam"); // 尝试将非Structure类型加入字段顺序 } } // 调用示例 Install_CD97_GTML pxInstallCardCD97 = new Install_CD97_GTML(); CD97_GTML_Parameter pxCD97_GTML_Parameter = new CD97_GTML_Parameter(); pxInstallCardCD99.xCardType = 1; pxCD97_GTML_Parameter.ucAddReader = 0; pxCD97_GTML_Parameter.ucProtocolType = 1; pxInstallCardCD97.iCardParam = pxCD97_GTML_Parameter; // res = ReaderThalesApi.INSTANCE.sSmartInstCardEx(pxInstallCardCD97); // 抛出异常
执行上述代码会得到java.lang.IllegalArgumentException: Invalid Structure field in class Install_CD97_GTML, field name ‘iCardParam’ (class CD97_GTML_Parameter): The type “CD97_GTML_Parameter” is not supported: Native size for type “CD97_GTML_Parameter” is unknown。
这个错误清晰地表明：JNA无法确定CD97_GTML_Parameter这个Java类型在原生内存中的大小和布局，因为它不是一个Structure或Union的子类。JNA需要这些继承关系来理解如何将Java对象序列化到原生内存，或从原生内存反序列化到Java对象。
解决方案：两种策略
针对上述问题，我们有两种主要的解决方案。
方案一：直接JNA映射（推荐用于严格对应C结构）
这种方法要求所有表示C语言结构体或联合体的Java类都必须继承Structure或Union。
- 将所有嵌套结构体定义为Structure子类：CD97_GTML_Parameter需要继承Structure。
- 将C联合体定义为Union子类：InstallCardParam需要继承Union。
- 正确定义getFieldOrder()： 每个Structure或Union子类都必须重写getFieldOrder()方法，返回一个包含其所有字段名称（按照C结构体/联合体中的声明顺序）的List<String>。
以下是根据C语言定义修正后的JNA映射：
import com.sun.jna.Structure; import com.sun.jna.Union; import java.util.Arrays; import java.util.List; // 对应 C 语言的 Install_CD97_GTML_Params 结构体 public class Install_CD97_GTML_Params_Native extends Structure { public byte ucProtocolType; public byte ucAddReader; public Install_CD97_GTML_Params_Native() { // 默认构造函数 } public Install_CD97_GTML_Params_Native(byte ucProtocolType, byte ucAddReader) { this.ucProtocolType = ucProtocolType; this.ucAddReader = ucAddReader; } @Override protected List<String> getFieldOrder() { return Arrays.asList("ucProtocolType", "ucAddReader"); } } // 对应 C 语言的 InstallCardParam 联合体 public class InstallCardParam_Native extends Union { // 联合体的成员，JNA会为其中最大的成员分配内存 public Install_CD97_GTML_Params_Native xCd97Param; // 其他联合体成员，例如： // public Install_CD98_GTML_Params_Native xCd98Param; public InstallCardParam_Native() { // 默认构造函数 } @Override protected List<String> getFieldOrder() { // 联合体字段顺序，通常只列出所有成员 return Arrays.asList("xCd97Param"); // 如果有其他成员，也需要在此列出 } } // 对应 C 语言的 InstallCard 结构体 public class InstallCard_Native extends Structure { public int xCardType; // 假设 eTypCardType 映射为 int public InstallCardParam_Native iCardParam; // 嵌套的联合体字段 public InstallCard_Native() { // 默认构造函数 } @Override protected List<String> getFieldOrder() { return Arrays.asList("xCardType", "iCardParam"); } }
使用示例：
// 假设 ReaderThalesApi 是 JNA 接口，定义了 sSmartInstCardEx 方法 // public interface ReaderThalesApi extends Library { // ReaderThalesApi INSTANCE = Native.load("your_native_lib", ReaderThalesApi.class); // short sSmartInstCardEx(InstallCard_Native pxInstallCard); // } InstallCard_Native pxInstallCard = new InstallCard_Native(); pxInstallCard.xCardType = 1; // 为联合体成员赋值 Install_CD97_GTML_Params_Native cd97Params = new Install_CD97_GTML_Params_Native((byte)1, (byte)0); pxInstallCard.iCardParam.xCd97Param = cd97Params; // 对于联合体，通常需要显式地设置当前活跃的类型，以便JNA正确处理 pxInstallCard.iCardParam.setType(Install_CD97_GTML_Params_Native.class); // 将数据写入原生内存（如果需要） pxInstallCard.write(); // 调用原生方法 // short res = ReaderThalesApi.INSTANCE.sSmartInstCardEx(pxInstallCard); // 从原生内存读取数据（如果方法会修改结构体内容） // pxInstallCard.read();
方案二：“友好”对象转换（推荐用于分离JNA与业务逻辑）
当C语言结构体非常复杂，或者你希望在java应用程序中使用更简洁、更符合Java习惯的POJO（Plain Old Java Object）时，可以采用“友好”对象转换策略。这种方法将JNA相关的Structure类作为内部实现细节，对外提供一组更易用的POJO。
- 定义友好的POJO类： 这些类不需要继承Structure，它们是纯粹的Java对象，用于承载业务数据。
- 定义JNA Structure类： 按照方案一的方式，定义严格遵循C结构体的JNA Structure和Union类。
- 实现转换逻辑： 编写转换方法，将友好的POJO实例转换为JNA Structure实例，反之亦然。
以下是“友好”对象转换的示例：
// 友好的参数类，不继承Structure public class Friendly_CD97_GTML_Parameter { public final byte ucProtocolType; public final byte ucAddReader; public Friendly_CD97_GTML_Parameter(byte ucProtocolType, byte ucAddReader) {
