使用JNA将C结构体映射到Java时出现输入错误问题排查

1. 严格对齐FfiStr的C与JNA定义 #

C侧典型的FfiStr结构通常是：

typedef struct {
    const char* data;
    size_t len;
} FfiStr;

你的JNA映射必须完全匹配字段顺序和类型，不能偷工减料：

public static class FfiStr extends Structure {
    public Pointer data;
    public NativeLong len;

    public FfiStr() {}
    
    // 推荐的字符串构造方法，处理UTF-8字节长度
    public FfiStr(String value) {
        byte[] bytes = value.getBytes(StandardCharsets.UTF_8);
        data = new Memory(bytes.length + 1); // 额外分配null终止符空间（如果C侧需要）
        data.write(0, bytes, 0, bytes.length);
        len = new NativeLong(bytes.length);
    }

    @Override
    protected List<String> getFieldOrder() {
        return Arrays.asList("data", "len");
    }
}

关键错误点：

• 别直接用String映射const char*，JNA自动处理的null终止符会导致len字段和实际字节数不匹配，C侧校验时会判定输入无效。
• size_t必须用NativeLong，32/64位平台长度不同，用int会导致64位平台上长度截断。

2. 检查FfiStrList的映射与初始化 #

如果create_schema用到FfiStrList，C侧一般定义为：

typedef struct {
    FfiStr* items;
    size_t count;
} FfiStrList;

对应的JNA映射：

public static class FfiStrList extends Structure {
    public FfiStr[] items;
    public NativeLong count;

    public FfiStrList(FfiStr[] strArray) {
        items = strArray;
        count = new NativeLong(strArray.length);
        // 必须显式分配内存给结构体数组，否则C侧会读取到无效指针
        for (FfiStr str : items) {
            str.write();
        }
    }

    @Override
    protected List<String> getFieldOrder() {
        return Arrays.asList("items", "count");
    }
}

常见坑：

• 用String[]直接替代FfiStr[]，完全不符合C侧的结构要求，必然触发输入错误。
• 初始化时count值和items数组长度不匹配，或者没给FfiStr实例调用write()分配内存。

3. 核对create_schema的函数签名映射 #

C侧create_schema的签名通常类似：

int create_schema(ObjectHandle* out_handle, FfiStr schema_name, FfiStrList fields);

JNA接口必须严格匹配参数顺序和类型：

int create_schema(PointerByReference out_handle, FfiStr schema_name, FfiStrList fields);

注意：ObjectHandle*用PointerByReference映射，确保能接收C侧返回的句柄指针，别用Pointer否则无法正确接收输出。

4. 调用时的参数构造校验 #

调用create_schema时，必须保证每个参数的有效性：

// 构造schema名称的FfiStr
FfiStr schemaName = new FfiStr("user_profile");
// 构造字段列表的FfiStr数组
FfiStr[] fields = {
    new FfiStr("user_id"),
    new FfiStr("user_name")
};
FfiStrList fieldList = new FfiStrList(fields);

// 准备接收输出句柄
PointerByReference outHandle = new PointerByReference();
int result = yourNativeLib.create_schema(outHandle, schemaName, fieldList);

容易忽略的错误：

• 构造FfiStr时用value.length()作为len，这是字符数，不是UTF-8字节数，中文等多字节字符会导致长度不匹配。
• 没有给FfiStr分配内存就传入，比如直接用空构造函数但没赋值data和len。

5. 辅助排查手段 #

• 打印FfiStr和FfiStrList的结构内容：用schemaName.toString()查看data指针地址和len值，确认是否符合预期。
• 如果C侧有日志输出，直接查看具体的输入错误细节，定位是哪个参数不合法。
• 既然create_link_secret和generate_nonce正常，说明JNA的库加载、调用约定（比如stdcall/cdecl）没问题，不用怀疑基础配置。

内容的提问来源于stack exchange，提问作者Zerokerim