Java ServiceLoader 隔离模块化插件实现

Java 的模块化插件要同时解决“发现实现”和“隔离依赖”两个问题。ServiceLoader 只负责按服务契约发现 provider；真正的隔离边界应由 ModuleLayer 与 ClassLoader 建立。一个实用结构是：把稳定的插件 API 放在父层，为每个插件目录分别解析 Configuration、创建子 ModuleLayer，再调用 ServiceLoader.load(layer, Plugin.class)。

Java 官方学习入口：https://dev.java/

下面的实现采用“一插件目录一子层”。每个插件可以携带自己的模块化依赖；宿主与插件只共享父层中的 plugin.api。这样既避免实现类硬编码，也减少两个插件因同名依赖、不同版本或初始化失败产生的连锁影响。

隔离结构：API 在父层，实现留在子层

父层通常是应用启动时的 boot layer，包含宿主模块和共享 API 模块。插件实现模块及其私有依赖放在独立目录，由运行期 ModuleFinder 发现。最重要的规则是：插件目录不要再次打包 plugin.api，否则服务接口可能由不同类加载器定义，最终出现“类名相同但类型不相等”的问题。

先定义一个窄而稳定的插件契约

插件 API 不要暴露宿主内部对象图，也不要让插件直接拿到数据库连接池、线程池实现或可变全局状态。更稳妥的做法是传入一个只包含允许能力的上下文，并让插件显式释放自己创建的资源。

package com.example.plugin.api;

public interface Plugin extends AutoCloseable {
    // 返回稳定且唯一的插件标识，宿主用它检测重复加载。
    String id();

    // 启动时只接收受控上下文，不暴露宿主内部实现。
    void start(PluginContext context) throws Exception;

    @Override
    default void close() throws Exception {
        // 无资源的简单插件可以保留默认空实现。
    }
}

package com.example.plugin.api;

import java.util.Map;
import java.util.logging.Logger;

public record PluginContext(
        Logger logger,
        Map config
) {
    // 复制配置，避免插件修改宿主持有的可变 Map。
    public PluginContext {
        config = Map.copyOf(config);
    }
}

API 模块只导出契约包：

module plugin.api {
    // 只有公开 SPI 包对宿主和插件可见。
    exports com.example.plugin.api;
}

宿主 uses，插件 provides

ServiceLoader 在命名模块中依赖模块描述符。宿主声明自己消费服务，插件声明具体 provider。不要为了省事把实现包 exports 给宿主；ServiceLoader 可以根据 provides ... with ... 创建 provider。

module host.app {
    // 宿主只依赖稳定 API，不直接依赖任何插件实现。
    requires plugin.api;

    // 声明服务依赖，供模块解析和 ServiceLoader 使用。
    uses com.example.plugin.api.Plugin;
}

module plugin.greeter {
    // provider 编译和运行时都读取父层中的共享 API。
    requires plugin.api;

    // 实现类无需导出给宿主，由 ServiceLoader 负责实例化。
    provides com.example.plugin.api.Plugin
        with com.example.plugin.greeter.GreeterPlugin;
}

GreeterPlugin 应是 public provider，并提供可被 ServiceLoader 使用的构造方式。实现类所在包可以保持未导出，从而缩小插件的公开表面。

运行期加载器：解析、建层、发现、回滚

加载一个插件目录时，先用 ModuleFinder 找到模块，再以 boot layer 的 Configuration 为父配置执行解析。resolveAndBind 会在普通模块解析基础上加入服务绑定；随后为本目录创建独立子层。因为每次调用都新建一个层，即使每层内部使用 one-loader 策略，不同插件目录之间仍拥有不同类加载器。

package com.example.host;

import com.example.plugin.api.Plugin;
import com.example.plugin.api.PluginContext;

import java.lang.module.Configuration;
import java.lang.module.ModuleFinder;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.ServiceLoader;
import java.util.Set;
import java.util.stream.Collectors;

public final class PluginManager implements AutoCloseable {
    private final Map loaded = new LinkedHashMap();

    public List loadDirectory(
            Path pluginDir,
            PluginContext context
    ) {
        // 只在当前插件目录查找模块，目录间不合并 ModuleFinder。
        ModuleFinder finder = ModuleFinder.of(pluginDir);
        Set roots = finder.findAll().stream()
                .map(ref -> ref.descriptor().name())
                .collect(Collectors.toUnmodifiableSet());

        if (roots.isEmpty()) {
            throw new IllegalArgumentException("插件目录没有可解析模块: " + pluginDir);
        }

        ModuleLayer parent = ModuleLayer.boot();
        Configuration configuration = parent.configuration()
                .resolveAndBind(finder, ModuleFinder.of(), roots);

        // 每个插件目录创建一个新子层，因此获得独立的类加载器边界。
        ModuleLayer layer = parent.defineModulesWithOneLoader(
                configuration,
                ClassLoader.getSystemClassLoader()
        );

        ServiceLoader services =
                ServiceLoader.load(layer, Plugin.class);
        List started = new ArrayList();

        try {
            // stream() 允许先观察 provider 类型，再按需创建实例。
            for (ServiceLoader.Provider provider
                    : services.stream().toList()) {
                Plugin plugin = provider.get();
                if (loaded.containsKey(plugin.id())) {
                    throw new IllegalStateException(
                            "插件标识重复: " + plugin.id()
                    );
                }

                // 先加入回滚列表，start() 半途失败时也能调用 close()。
                started.add(plugin);
                plugin.start(context);
            }

            if (started.isEmpty()) {
                throw new IllegalStateException(
                        "模块已解析，但没有发现 Plugin provider"
                );
            }

            // 启动全部成功后再提交到注册表，避免暴露半初始化状态。
            started.forEach(plugin -> loaded.put(
                    plugin.id(),
                    new LoadedPlugin(layer, plugin)
            ));
            return started.stream().map(Plugin::id).toList();
        } catch (RuntimeException | Error failure) {
            // 逆序关闭已启动实例，保留原始异常并追加清理异常。
            closeReverse(started, failure);
            throw failure;
        } catch (Exception failure) {
            closeReverse(started, failure);
            throw new IllegalStateException("插件启动失败", failure);
        }
    }

    private static void closeReverse(
            List plugins,
            Throwable original
    ) {
        for (int i = plugins.size() - 1; i >= 0; i--) {
            try {
                plugins.get(i).close();
            } catch (Exception cleanupFailure) {
                // 清理错误作为 suppressed 附着，不覆盖真正的启动原因。
                original.addSuppressed(cleanupFailure);
            }
        }
    }

    @Override
    public void close() {
        List items =
                new ArrayList(loaded.values());
        loaded.clear();

        for (int i = items.size() - 1; i >= 0; i--) {
            try {
                items.get(i).plugin().close();
            } catch (Exception cleanupFailure) {
                // 生产代码应把清理失败写入结构化日志并继续关闭其余插件。
                System.err.println(cleanupFailure.getMessage());
            }
        }
    }

    private record LoadedPlugin(
            ModuleLayer layer,
            Plugin plugin
    ) {
        // 同时保留层和实例，确保插件运行期间类型仍可达。
    }
}

这个示例把“发现到 provider”与“插件已可用”分开处理：只有当前目录内所有 provider 都启动成功，才写入注册表。若其中一个失败，已启动实例按逆序关闭，避免用户看到一半可用、一半失效的插件状态。

为什么不是把所有插件放进同一个层

如果所有插件目录合并到一个 ModuleFinder，再用一个 ModuleLayer 加载，模块系统仍能检查可读性，但插件之间会共享同一套解析结果。常见后果包括：

• 两个插件携带同名模块但版本不同，ModuleFinder 无法给它们各自选择版本；
• 同一类加载器中的模块出现重叠包或 split package，建层直接失败；
• 升级一个插件需要重新创建包含其他插件的整个层；
• 错误的共享依赖让插件在开发环境可用，部署后却读取到另一版本。

一目录一子层把解析范围缩小到当前插件。插件 A 与插件 B 都读取父层的 API，但不直接读取彼此的实现模块。需要插件协作时，应通过父层定义的另一条服务契约通信，而不是跨层强制加载实现类。

隔离不等于安全沙箱

ModuleLayer 和 ClassLoader 解决的是模块可读性、类型身份与依赖冲突，不会把不受信任代码变成安全代码。插件仍在同一 JVM 进程内运行，可能创建线程、访问文件、发起网络请求或终止进程。对于第三方不可信插件，应使用独立进程、操作系统权限、容器策略和受限通信协议建立安全边界。

卸载与升级的真实边界

Java 没有“关闭 ModuleLayer”方法。让插件类有机会被回收，需要同时满足以下条件：

• 先调用插件的 close()，停止线程、定时任务和监听器；
• 从宿主注册表、事件总线、缓存和 ThreadLocal 中移除插件对象；
• 释放 JDBC 驱动、日志处理器、文件监控器等外部资源；
• 删除对 ServiceLoader、ModuleLayer、ClassLoader、Class 和实例的强引用；
• 不把“触发 GC”当作确定性的卸载完成信号。

ServiceLoader.reload() 只会清除该 loader 的 provider 缓存，让后续迭代重新发现；它不会卸载模块或类。热升级通常采用“创建新子层—启动新实例—切换路由—关闭旧实例—释放旧引用”的替换策略。

常见失败怎样定位

实现时的验收清单

• 共享 API 只在父层出现一次，插件包不重复携带；
• 宿主声明 uses，插件声明 provides ... with ...；
• 每个插件目录独立建立 ModuleFinder、Configuration 和 ModuleLayer；
• ServiceLoader 明确绑定目标 layer，不依赖线程上下文类加载器猜测；
• provider 初始化全部成功后才对外发布插件状态；
• 失败时逆序释放资源，清理异常不覆盖原始异常；
• 不把模块隔离误当成恶意代码沙箱；
• 升级通过新旧层切换完成，不承诺确定性类卸载。

ServiceLoader、Configuration 与 ModuleLayer 组合后的价值，不只是“少写一个反射工厂”，而是把插件契约、模块解析、类加载和生命周期各自放到清晰边界中。共享 API 越窄，子层越独立，插件系统在升级、冲突和失败时就越容易保持可预测。

参考资料

• Java SE 25 ServiceLoader API
• Java SE 25 ModuleLayer API
• Java SE 25 Configuration API
• Java SE 25 ModuleFinder API