本文详解 Java 9+ 模块系统中 ServiceLoader.load(ModuleLayer, Class) 调用失败的根本原因——模块未声明 uses/provides 关系，并提供符合 JEP 261 规范的标准化配置方法及实战代码示例。
本文详解 java 9+ 模块系统中 `serviceloader.load(modulelayer, class)` 调用失败的根本原因——模块未声明 `uses`/`provides` 关系，并提供符合 jep 261 规范的标准化配置方法及实战代码示例。
在基于 ModuleLayer 的插件化架构中，许多开发者（如问题中的 Wexalian）会遇到一个典型陷阱：调用 ServiceLoader.load(layer, ServiceInterface.class) 时抛出 ServiceConfigurationError，提示“module does not declare uses”，即使目标服务接口已存在于模块路径中。根本原因并非 PluginLoader 实现有误，而是 Java 模块系统对服务发现施加了严格的编译期契约约束——它不依赖运行时类路径扫描，而完全依赖模块描述符（module-info.java）中显式声明的服务契约。
✅ 正确的模块服务契约配置
Java 的 ServiceLoader 在模块环境下（尤其是使用 ServiceLoader.load(ModuleLayer, Class) 时）严格遵循以下规则：
-
服务消费者模块（即加载服务的模块，如你的主应用或 com.wexalian.common.plugin 库）必须在 module-info.java 中声明：
uses com.wexalian.common.plugin.IAbstractPlugin;
-
服务提供者模块（即每个插件 JAR）必须在自己的 module-info.java 中声明：
provides com.wexalian.common.plugin.IAbstractPlugin with some.plugin.MyPluginImplementation;
⚠️ 注意：provides 后必须是具体实现类（非工厂类，除非该工厂类本身实现了 IAbstractPlugin），且该类必须具有无参公共构造器（否则 ServiceLoader.Provider::get() 将抛出 ServiceConfigurationError）。
? 示例：完整模块配置链
假设你的项目结构如下：
立即学习“Java免费学习笔记（深入）”；
app-module/ ← 主应用（消费者） common-plugin/ ← 公共库（含 IAbstractPlugin 接口） plugin-example/ ← 插件模块（提供者）
1. common-plugin/module-info.java
module com.wexalian.common.plugin {
exports com.wexalian.common.plugin;
// ✅ 声明本模块“使用”该服务接口
uses com.wexalian.common.plugin.IAbstractPlugin;
}2. plugin-example/module-info.java
module plugin.example {
requires com.wexalian.common.plugin;
// ✅ 声明本模块“提供”该服务的具体实现
provides com.wexalian.common.plugin.IAbstractPlugin
with plugin.example.ExamplePlugin;
}3. app-module/module-info.java
module my.application {
requires com.wexalian.common.plugin;
// ✅ 主应用也需声明 uses（若直接调用 ServiceLoader）
uses com.wexalian.common.plugin.IAbstractPlugin;
}? 为什么 Reflection.getCallerClass() 不是问题根源？
问题中提到 ServiceLoader “内部使用 Reflection.getCallerClass() 获取调用方模块”，这虽属实（用于定位 ModuleLayer 上下文），但真正触发失败的是模块解析阶段：当 ServiceLoader 尝试从指定 ModuleLayer 查找 IAbstractPlugin 的提供者时，它会检查调用方模块是否在 uses 子句中声明了该服务。若未声明，JVM 直接拒绝服务发现，根本不会进入类加载流程——因此补丁式绕过（如传入 Function
? 实战建议：增强 PluginLoaderImpl 的健壮性
虽然模块契约是前提，你仍可在代码层做防御性检查，避免模糊错误：
static <T> Stream<T> safeStream(ModuleLayer layer, Class<T> service) {
// 验证调用方模块是否声明 uses（可选：仅开发期启用）
Module caller = StackWalker.getInstance()
.getCallerClass().getModule();
if (!caller.getDescriptor().uses().stream()
.map(ModuleDescriptor.Uses::service)
.anyMatch(s -> s.equals(service.getName()))) {
throw new IllegalStateException(
String.format("Module '%s' must declare 'uses %s;' to load services",
caller.getName(), service.getName()));
}
return serviceLoaderLayer.stream(layer, service);
}✅ 总结
| 问题现象 | 根本原因 | 解决方案 |
|---|---|---|
| ServiceLoader.load(layer, T.class) 报错 “module does not declare uses” | 消费者模块缺失 uses 声明；或提供者模块缺失 provides 声明 | ✅ 双向强制声明： • 消费者：uses com.example.ServiceInterface • 提供者：provides com.example.ServiceInterface with impl.Class |
模块化服务加载不是“让类可见”，而是“让契约可见”。抛弃传统 classpath 思维，严格遵循 module-info.java 的服务契约声明，才是 ServiceLoader 与 ModuleLayer 协同工作的唯一正解。
