Java Linker API 怎么调用简单本地函数

Java 22 开始，Foreign Function and Memory API 已正式定稿。调用一个简单本地函数的最短路径是：用 Linker.nativeLinker() 取得当前平台链接器，用 SymbolLookup 找到函数地址，用 FunctionDescriptor 描述 C 签名，再把参数放入 MemorySegment 后调用生成的 MethodHandle。下面以 C 标准库的 strlen 为例，不需要编写 JNI 胶水代码。

本文示例面向 JDK 22 和 64 位 Linux/macOS。它调用当前 Java 进程默认可见的 strlen，并显式启用本地访问权限。Windows 或自定义动态库需要另外确认库名、符号来源与 ABI 映射。

先看最小调用模型

Linker API 不是“按函数名自动猜签名”的反射工具。本地符号通常只有地址，没有足够的参数与返回类型信息，因此 Java 端必须同时提供地址和准确的函数描述符。

strlen 的 C 原型是 size_t strlen(const char *s)。在常见 64 位 Linux/macOS 环境中，可以把返回的 size_t 映射为 JAVA_LONG，把 const char* 映射为 ADDRESS。这是明确的平台假设，不应该无条件复制到所有 ABI。

完整示例：调用 C strlen

把下面代码保存为 NativeStrlen.java。示例将 Java 字符串编码为以 NUL 结尾的 UTF-8 本地字符串，然后调用 strlen 计算字节数。

import java.lang.foreign.Arena;
import java.lang.foreign.FunctionDescriptor;
import java.lang.foreign.Linker;
import java.lang.foreign.MemorySegment;
import java.lang.invoke.MethodHandle;

import static java.lang.foreign.ValueLayout.ADDRESS;
import static java.lang.foreign.ValueLayout.JAVA_LONG;

public final class NativeStrlen {
    public static void main(String[] args) throws Throwable {
        // 使用当前操作系统与处理器对应的本地 ABI。
        Linker linker = Linker.nativeLinker();

        // 默认查找器覆盖当前 Java 进程暴露的常用本地库符号。
        MemorySegment strlenAddress = linker.defaultLookup()
                .find("strlen")
                .orElseThrow(() -> new IllegalStateException("当前平台未找到 strlen 符号"));

        // 本例限定 64 位平台：size_t 映射为 long，const char* 映射为地址。
        FunctionDescriptor strlenDescriptor = FunctionDescriptor.of(JAVA_LONG, ADDRESS);
        MethodHandle strlen = linker.downcallHandle(strlenAddress, strlenDescriptor);

        // confined Arena 将本地内存生命周期限制在当前线程和代码块内。
        try (Arena arena = Arena.ofConfined()) {
            MemorySegment text = arena.allocateFrom("linker-api");
            long byteLength = (long) strlen.invokeExact(text);
            System.out.println("UTF-8 字节长度：" + byteLength);
        }
    }
}

Arena.allocateFrom(String) 会创建以 NUL 结尾的 UTF-8 数据，因此可直接对应 C 的字符串指针。结果是字节数而不是 Java 的 UTF-16 代码单元数；当字符串包含中文或表情时，两者通常不同。

编译与运行时要显式授权

downcallHandle 属于受限方法。类路径程序运行在未命名模块中，应使用 --enable-native-access=ALL-UNNAMED 明确授权，而不是依赖警告或宽松默认行为。

# 使用 JDK 22 编译单文件示例
javac NativeStrlen.java

# 为类路径中的未命名模块授予本地访问权限
java --enable-native-access=ALL-UNNAMED NativeStrlen

对具名模块，参数应改为具体模块名，例如 --enable-native-access=com.example.nativebridge。生产部署不要为了省事给无关模块开放权限；本地调用本质上可以绕过 Java 的常规内存安全保证。

在上述限定环境中，linker-api 由 10 个 ASCII 字节组成，因此输出应为：

UTF-8 字节长度：10

生产封装要守住四个边界

1. 固定 ABI 假设

FunctionDescriptor 必须与真实 C 函数完全一致。参数数量、顺序、返回布局、结构体对齐或调用约定任一处错误，都不是普通业务异常。若要跨 32 位与 64 位环境，优先读取 linker.canonicalLayouts() 中的 size_t 布局，并根据其载体类型构造平台适配层。

2. 限制符号来源

defaultLookup() 适合演示标准库函数。业务动态库应使用受控的 SymbolLookup.libraryLookup，把库路径交给部署配置管理，并限制目录写权限。不要让请求参数、用户上传目录或临时目录决定待加载库。

3. 绑定内存生命周期

本地指针必须在所属 Arena 有效期内使用。关闭 Arena 后继续保存或传递对应的 MemorySegment 是错误设计。同步、短调用可优先使用 Arena.ofConfined()；跨线程共享之前，应先明确所有权、并发访问和释放时机，而不是简单改成全局 Arena。

4. 缩小本地访问面

将 Linker、函数描述符和 MethodHandle 封装进一个不可变的基础设施类，只暴露经过类型检查的 Java 方法。业务层不应直接接触函数地址，也不应动态拼装函数描述符。记录库版本、目标平台和启动参数，但不要把指针值、敏感路径或原始内存内容写入日志。

常见错误怎么定位

从简单函数扩展到业务库

掌握 strlen 后，接入业务库时仍沿用同一组概念：明确加载哪个库、查找哪个符号、按头文件写出准确描述符、为指针数据分配受控内存，并把原生错误转换为稳定的 Java 异常。复杂点只是在结构体、回调、返回指针和资源释放上增加更多布局与生命周期规则。

如果函数返回本地分配的指针，还必须找到与它配套的释放函数；如果本地代码要回调 Java，则需要 upcallStub，并确保存根和它引用的 Arena 在回调期间始终有效。不要把一次成功调用当成可上线证明，生产前至少要覆盖符号缺失、空指针、边界长度、并发访问和库版本不匹配等故障路径。

小结

Java Linker API 调用简单本地函数的核心只有两个输入：真实函数地址和与 ABI 完全一致的 FunctionDescriptor。MemorySegment 负责承载指针数据，Arena 负责约束生命周期，MethodHandle 则提供 Java 调用入口。最小示例容易写，真正需要谨慎的是平台差异、权限范围和内存所有权。

相关官方资料：https://openjdk.org/jeps/454

JDK 22 Linker API：https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/foreign/Linker.html