Java基于第三方库极速调用Python生态的实战教学_Java

在混合语言开发、ai agent 执行沙箱或跨语言胶水层开发中，我们常常需要在 java 服务中直接执行 python 脚本，并复用 python 繁荣的第三方库生态（如 requests、numpy、pandas 等）。

以往常见的方案是使用 jython（仅支持 python 2.7，已基本停滞）或直接通过 processbuilder 启动子进程（跨进程通信开销大、性能损耗明显）。

graalvm polyglot api + graalpy 提供了革命性的解法：它直接在 jvm 内部提供高性能的 python 3 运行时环境，支持跨语言内存直接互操作。本文基于一次完整的 windows 环境实战，详细记录如何在 java 中加载外部 python 虚拟环境第三方库，以及排查模块路径与 c 扩展警告的全过程。

1. 核心技术栈与架构原理

graalvm polyglot api：graalvm 提供的多语言统一嵌入接口，允许在 java、python、javascript、ruby、wasm 之间进行无缝调用与数据结构互操作。
graalpy：基于 truffle 框架实现的 python 3 运行时，不仅支持纯 python 代码，还内置了 cpython c-api 桥接层，能够加载并执行 c/c++ 扩展模块。

2. 准备工作

2.1 引入 maven 依赖

在标准 spring boot / java 项目中引入 graalvm polyglot 核心与 python 运行时依赖（建议搭配 jdk 21+）：

<dependencies>
    <!-- graalvm polyglot 统一 api -->
    <dependency>
        <groupid>org.graalvm.polyglot</groupid>
        <artifactid>polyglot</artifactid>
        <version>24.1.0</version>
    </dependency>
    <!-- 嵌入式 graalpy 引擎 -->
    <dependency>
        <groupid>org.graalvm.polyglot</groupid>
        <artifactid>python</artifactid>
        <version>24.1.0</version>
        <type>pom</type>
    </dependency>
</dependencies>

2.2 构建 python 虚拟环境并安装依赖

在本地终端（如 windows cmd/powershell）中初始化虚拟环境并安装目标库：

# 1. 创建虚拟环境至指定目录
python -m venv d:\data\my_python_env
# 2. 激活并安装三方库
d:\data\my_python_env\scripts\activate
pip install requests pyyaml

3. 实战代码：java 加载虚拟环境并执行三方库

在 java 代码中配置 polyglot context 时，显式指定 python.pythonpath 和 python.executable 是让 graalpy 成功找到第三方库的关键。

package com.example.demo.main;

import org.graalvm.polyglot.context;
import org.graalvm.polyglot.value;
import org.graalvm.polyglot.io.ioaccess;

import java.io.file;

public class graalpydemo {

    public static void main(string[] args) {
        string venvroot = "d:\\data\\my_python_env";
        string pythonexe = venvroot + "\\scripts\\python.exe";
        string sitepackages = venvroot + "\\lib\\site-packages";

        // 构建 polyglot context
        try (context context = context.newbuilder("python")
                .allowio(ioaccess.all)               // 允许读取磁盘依赖包
                .allownativeaccess(true)             // 允许加载 c 扩展模块
                .allowallaccess(true)
                .option("python.executable", pythonexe)      // 指定 python 解释器
                .option("python.pythonpath", sitepackages)   // 显式指定第三方库目录
                .option("python.warnexperimentalfeatures", "false") // 关闭 c-api 试验性特性警告
                .build()) {

            system.out.println("=== 测试导入第三方库 (requests) ===");
            context.eval("python", """
                import sys
                import requests

                print(f"[python] requests 模块加载成功！")
                print(f"[python] requests 版本: {requests.__version__}")
                print(f"[python] requests 路径: {requests.__file__}")
                """);
        }
    }
}

4. 运行日志与核心要点解析

运行上述程序后，控制台成功打印如下日志：

=== 测试导入第三方库 (requests) ===
d:\data\my_python_env\lib\site-packages\urllib3\__init__.py:35: notopensslwarning: urllib3 v2 only supports openssl 1.1.1+, currently the 'ssl' module is compiled with 'graalvm jsse'. see: https://github.com/urllib3/urllib3/issues/3020
  warnings.warn(
[python::cextcontext] warning: loading c extension module _cpython_unicodedata ... support for the python c api is considered experimental.
[python] requests 模块加载成功！
[python] requests 版本: 2.34.2
[python] requests 路径: d:\data\my_python_env\lib\site-packages\requests\__init__.py
process finished with exit code 0

关键排坑与技术细节

1.解决modulenotfounderror: no module named 'requests'

原因：单纯指定 python.executable 时，在 windows 环境下如果缺少 .exe 后缀，或外部 cpython 虚拟环境的隔离机制导致 sys.path 未能自动对齐，graalpy 无法在默认路径下找到模块。
解法：通过 .option("python.pythonpath", sitepackages) 显式将 site-packages 目录注入上下文，或者在 python 脚本开头执行 sys.path.append(r'...')。

2.理解notopensslwarning: compiled with 'graalvm jsse'

原因：requests 底层依赖 urllib3 v2，而 urllib3 v2 默认期望检测到标准的 openssl 1.1.1+。在 graalvm 运行时中，python 的 ssl 模块是由 java 层的 jsse（java secure socket extension） 桥接实现的。
影响：此警告仅为协议提示，不影响实际的 https 网络请求功能。如果需要消除警告，也可以降级虚拟环境中的 urllib3 为 1.26.x 系列。

3.消除support for the python c api is considered experimental警告

原因：graalpy 正在通过其内部的 c-api 兼容层加载 _cpython_unicodedata 原生动态链接库（.pyd）。
解法：如需保持控制台整洁，直接在 context 构建时加入配置项：

.option("python.warnexperimentalfeatures", "false")

5. 总结

相比于传统的子进程（process）调用方式，graalvm polyglot api 具备以下核心优势：

同进程极速交互：无需经过 json / socket 序列化开销，直接实现跨语言对象共享与方法互调。
完整生态复用：通过灵活配置 python.pythonpath，可直接挂载本地虚拟环境中的各类第三方库。
安全沙箱可控：可通过 allowio、allownativeaccess 精准控制脚本的执行权限，非常适合作为 ai agent 或低代码平台的脚本执行沙箱。