Java ServiceLoader 找不到实现类时先检查什么

Java 的 ServiceLoader 找不到实现类时，先别急着改业务代码：优先检查实现类是否真的进入 JAR、META-INF/services 文件名是否等于服务接口的全限定名，以及模块化项目有没有同时写好 uses 和 provides ... with ...。这类问题通常发生在“源码里有实现，打包后却发现不到”的边界。

官方 API 文档：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/ServiceLoader.html

为什么 ServiceLoader 找不到实现类

ServiceLoader 做的是 SPI 发现，不是扫描整个 classpath。调用 load(MyService.class) 后，它按照服务接口和可见的类加载范围寻找提供者；真正遍历或取得实例时，才可能加载实现类。因此“返回空迭代器”和“遍历时抛出 ServiceConfigurationError”不是同一种故障。

常见原因可以先按下面的边界分开：

先确认服务声明文件有没有进入 JAR

非模块化 JAR 需要在 META-INF/services 下放一个配置文件，文件名就是服务接口的全限定二进制名，例如接口是 com.example.spi.Formatter，文件就必须是 META-INF/services/com.example.spi.Formatter。文件内容每行写一个实现类的全限定名，不能写 .class 后缀；官方契约要求该配置文件使用 UTF-8，空白行和 # 后的注释会被忽略。

排查时直接看最终产物，而不是只看源码目录：

# 先确认服务声明文件确实进入最终 JAR
jar tf app.jar | grep 'META-INF/services/'

# 再读取文件内容，核对接口文件名和实现类全限定名
unzip -p app.jar META-INF/services/com.example.spi.Formatter

如果第二条命令提示找不到文件，问题在资源复制或打包配置；如果能读到文件但仍为空，检查构建插件是否覆盖了同名资源。文件里应类似下面这样，每行一个实现类：

# 配置文件不是 Java 源码，不要写 .class 后缀
com.example.format.JsonFormatter
com.example.format.XmlFormatter # 可选说明

模块化项目还要核对 uses 和 provides

如果项目使用 Java 模块，不能只保留传统的 META-INF/services 思路。消费方模块需要声明服务依赖：

// 消费方只声明“要使用”哪个服务接口
module app.main {
    requires com.example.spi;
    uses com.example.spi.Formatter;
}

提供方模块则声明实现关系：

// 提供方把实现绑定到服务接口，通常不必导出实现包
module formatter.json {
    requires com.example.spi;
    provides com.example.spi.Formatter
        with com.example.format.JsonFormatter;
}

这里的 uses 是消费方的声明，provides ... with ... 是提供方的声明，二者不能互相替代。服务接口所在模块还要让消费方可读；实现类需要满足 ServiceLoader 的提供者入口约定，例如使用可访问的公共构造器，或提供符合契约的公共静态 provider 方法。实现包是否 exports，不能简单当成所有问题的答案。

用同一个 ClassLoader 做最小验证

当应用容器、插件系统或测试运行器自带多个加载器时，优先显式使用应用实际的上下文 ClassLoader。这样能把“声明缺失”和“加载器看不到资源”分开：

import java.util.ServiceConfigurationError;
import java.util.ServiceLoader;

// 使用应用上下文加载器，避免排查代码换了一套可见范围
ClassLoader loader = Thread.currentThread().getContextClassLoader();
ServiceLoader services = ServiceLoader.load(Formatter.class, loader);

try {
    for (Formatter formatter : services) {
        // 走到这里才说明实现类已经被发现并成功创建
        System.out.println(formatter.getClass().getName());
    }
} catch (ServiceConfigurationError e) {
    // 发现声明但实例化失败时，保留原始原因继续查依赖和构造入口
    e.printStackTrace();
}

若显式加载器能发现、默认 load 却发现不到，重点比较两者加载的服务接口是否来自同一份类定义；若两者都发现不到，再回到 JAR 和模块声明。不要用“把所有 JAR 都塞进 classpath”掩盖边界问题，那会让插件隔离和重复版本冲突更难复现。

发布前按五项清单回归

1. 最终 JAR 中有正确路径的 META-INF/services 文件。
2. 文件名等于服务接口全限定名，内容没有错误包名和 .class 后缀。
3. 模块项目同时检查消费方 uses、提供方 provides、接口可读性。
4. 生产环境使用的 ClassLoader 能看到服务接口、实现类和它们的依赖。
5. 遍历时单独记录 ServiceConfigurationError，不要把空结果和初始化失败混为一谈。

常见问题

为什么源码里有实现类，JAR 里却找不到？

实现类本身不会自动生成类路径 SPI 声明。检查资源目录是否被打包，以及最终 JAR 是否包含对应的 META-INF/services 文件。

服务配置文件能不能写实现类的简单名？

不能。文件内容应写实现类的全限定二进制名，例如 com.example.format.JsonFormatter，不能写简单名或 .class 后缀。

模块化项目还需要 META-INF/services 吗？

命名模块优先通过 uses 和 provides ... with ... 表达服务关系；不要只补传统资源文件而遗漏模块描述符。

ServiceLoader 为什么遍历时才报错？

提供者发现和实例化具有惰性，调用 iterator 或实际取下一个实例时才可能暴露依赖缺失、构造器不可访问或 provider 方法异常。