在Java 9引入模块化系统后，ServiceLoader作为服务发现的核心工具，其加载逻辑和传统的类路径模式有了明显差异，很多开发者在新增模块后发现ServiceLoader无法获取到新模块中定义的服务变量，这需要从模块配置、服务声明、加载逻辑三个维度排查问题。
问题产生的核心原因
ServiceLoader在模块化环境下的加载依赖严格的模块声明和服务配置，常见的问题诱因主要有以下几类：
- 新模块的
module-info.java没有正确声明服务提供关系 - 服务接口或实现类没有按照模块化规范导出或开放
- 服务配置文件的位置或命名不符合模块化要求
- 加载ServiceLoader时使用的类加载器不符合模块化场景
分步排查与解决方案
1. 检查模块声明配置
首先确认新模块的module-info.java是否正确声明了服务提供。模块化环境下，服务提供者需要在模块描述符中使用provides...with...语句声明服务接口和对应的实现类，同时如果服务接口不在当前模块，还需要通过requires引入接口所在的模块。
假设我们有一个服务接口com.example.service.UserService，新模块com.example.user.module提供了它的实现com.example.user.module.impl.UserServiceImpl，正确的模块声明如下：
// 新模块的module-info.java
module com.example.user.module {
// 引入服务接口所在的模块
requires com.example.service.api;
// 声明服务提供关系，格式为 provides 服务接口全限定名 with 实现类全限定名
provides com.example.service.UserService with com.example.user.module.impl.UserServiceImpl;
}
如果缺少provides语句，ServiceLoader就无法感知到该模块提供的服务，自然无法加载对应的变量。
2. 确认类导出与开放规则
模块化系统中，类的可访问性受到模块导出规则的限制。如果服务实现类没有被正确导出或者开放，即使声明了服务提供，ServiceLoader也无法实例化该类。
如果服务实现类需要被其他模块访问，需要在模块声明中使用exports导出实现类所在的包；如果仅需要被ServiceLoader反射实例化，也可以使用opens开放对应的包，允许反射访问。示例如下：
module com.example.user.module {
requires com.example.service.api;
// 导出实现类所在的包，允许其他模块访问
exports com.example.user.module.impl;
provides com.example.service.UserService with com.example.user.module.impl.UserServiceImpl;
}
3. 检查服务配置文件（兼容传统模式场景）
如果你的项目同时兼容传统类路径和模块化环境，或者没有使用provides语句而是采用传统的服务文件配置方式，需要确认服务文件的位置和命名是否正确。传统模式下，服务配置文件需要放在META-INF/services/目录下，文件名是服务接口的全限定名，内容是实现类的全限定名。
在模块化项目中，如果采用传统配置方式，该目录需要放在模块的resources根目录下，文件内容示例如下：
# META-INF/services/com.example.service.UserService 文件内容 com.example.user.module.impl.UserServiceImpl
注意文件名不能有多余的后缀，内容中不能有空格或者多余的空行，否则会导致解析失败。
4. 验证ServiceLoader加载逻辑
加载ServiceLoader时，需要使用正确的类加载器。在模块化环境下，推荐使用服务接口的类加载器来加载服务，避免类加载器隔离导致的问题。正确的加载示例如下：
import java.util.ServiceLoader;
import com.example.service.UserService;
public class ServiceLoaderTest {
public static void main(String[] args) {
// 使用UserService接口的类加载器加载服务
ServiceLoader<UserService> services = ServiceLoader.load(UserService.class);
// 遍历获取所有服务实现
for (UserService service : services) {
System.out.println("加载到服务实现：" + service.getClass().getName());
}
}
}
如果遍历后没有输出新模块的实现类，可以检查当前运行时的模块路径是否包含了新模块，避免新模块没有被加入到运行时环境中。
常见问题排查清单
可以按照以下清单快速排查问题：
| 排查项 | 检查内容 |
|---|---|
| 模块声明 | 新模块是否包含provides 服务接口 with 实现类语句，是否引入接口所在模块 |
| 类访问性 | 实现类所在的包是否被exports或opens |
| 服务文件 | 传统模式下META-INF/services/下的文件命名和内容是否正确 |
| 运行时环境 | 新模块是否被加入到模块路径中，没有被遗漏 |
| 类加载器 | 加载ServiceLoader时是否使用了服务接口的类加载器 |
总结
模块化环境下ServiceLoader无法获取新模块变量的问题，本质都是配置不符合模块化规范导致的。只要按照模块声明、类访问性、服务配置、加载逻辑的顺序逐一排查，就能快速定位问题。优先推荐使用provides...with...的模块化声明方式，相比传统服务文件方式更符合模块化设计理念，也能减少配置出错的概率。
ServiceLoaderJava模块化模块变量服务加载修改时间：2026-07-12 23:54:26