Java ServiceLoader 在模块路径下为何找不到 provider

我第一次把普通 JAR 改成模块时，最容易误判的一点是：实现类明明在 JAR 里，ServiceLoader 却像“看不见”它。模块路径下的 provider 发现不再只看 META-INF/services，而是同时受消费方的 uses、提供方的 provides、模块可见性和实例化条件影响。先记住一句话：命名模块要在模块描述符里声明服务关系，自动模块或未命名模块才主要依赖服务配置文件。

如果是命名模块，先查消费模块有没有 uses、提供模块有没有 provides ... with ...，再查运行时是否真的把提供模块放进了同一个模块路径；不要用 classpath 的排查方法替代它。

模块路径下先分清两条发现规则

服务接口可以放在独立的 API 模块中，消费模块只依赖接口，提供模块负责实现。三者都在模块路径时，ServiceLoader 会按命名模块的模块描述符寻找 provider；这时服务实现不必导出实现包，但提供关系必须写进提供模块的 module-info.java。

如果实现位于普通 classpath JAR，文件名才是 META-INF/services/服务接口全限定名，文件内容逐行列出实现类。一个常见坑是：JAR 虽然放在 --module-path 上，但没有 module-info.class，它属于自动模块；这和显式命名模块的配置方式不同，不能只凭“路径里有 JAR”判断规则。

按 uses、provides 和可见性逐项排查

下面用 com.example.api、com.example.app 和 com.example.provider 表示三块边界。消费方的模块描述符至少要声明服务接口所在模块，并声明自己会使用该服务：

// com.example.app/module-info.java
module com.example.app {
    // 读取服务接口所在的 API 模块
    requires com.example.api;
    // 允许本模块通过 ServiceLoader 发现该服务
    uses com.example.api.Formatter;
}

// com.example.provider/module-info.java
module com.example.provider {
    // 提供方需要读取服务接口
    requires com.example.api;
    // 把当前模块中的实现绑定到服务接口
    provides com.example.api.Formatter
        with com.example.provider.JsonFormatter;
}

这里最容易漏掉的是 uses。命名模块直接调用 ServiceLoader.load(Formatter.class) 时，如果模块描述符没有声明使用关系，API 文档把它归为配置错误，而不是“列表为空”。另一边的 provides 只能指向当前提供模块中的 provider；实现类应为公开类，并提供公开无参构造器，或者提供公开静态无参 provider() 方法。

把“找不到”拆成模块路径和实例化两层

先看启动命令：提供模块必须实际出现在运行时的模块路径上，根模块也必须能解析到它。示例命令只展示边界，目录名应替换成自己的编译输出：

# 把三个模块的编译输出放到同一个模块路径
java --module-path out \
  --module com.example.app/com.example.app.Main

# 用模块描述符确认提供模块声明了哪个服务
jar --describe-module --file out/com.example.provider.jar

如果描述符和路径都正确，下一层才是 provider 本身。下面的诊断代码会在真正取出 provider 时暴露加载或实例化异常；不要只打印 ServiceLoader 对象本身：

ServiceLoader loader = ServiceLoader.load(Formatter.class);
try {
    // iterator 的 hasNext/next 可能在此处触发 provider 加载
    for (Formatter formatter : loader) {
        // 记录实际找到的实现类，区分发现成功与业务调用失败
        System.out.println(formatter.getClass().getName());
    }
} catch (ServiceConfigurationError error) {
    // 保留原始原因，重点检查构造器、provider 方法和模块可见性
    error.printStackTrace();
}

“完全没有 provider”和“找到后实例化失败”是两种问题：前者优先检查 uses、provides、模块路径和服务接口可读性；后者再检查 provider 是否实现了接口、是否有公开无参构造器，或 provider() 返回类型是否兼容。

几个容易混淆的边界

• 服务接口要可访问：消费模块必须能读取接口所在包；实现包则不必为了 ServiceLoader 而导出。
• 配置文件不是万能补丁：命名模块应以 provides 为主，不能把配置文件当成缺失模块声明的替代品。
• 模块层要单独判断：使用自定义 ModuleLayer 时，优先确认加载器和层中是否包含 provider，必要时使用对应层的 ServiceLoader 入口。

相关问题

为什么 classpath 能发现，改成 module-path 就不行？因为两种部署形态使用不同元数据：classpath 主要读取 META-INF/services，命名模块依赖 uses 与 provides。

provider 已找到但仍抛 ServiceConfigurationError 怎么办？先看异常原因，再核对实现类的公开构造器或公开静态 provider() 方法、返回类型和模块可见性；这已经属于实例化阶段，不是发现规则本身。

排查时可以按“消费声明—提供声明—运行路径—实例化条件”的顺序做四项核对。只要把模块路径上的 JAR 类型和对应元数据分开看，ServiceLoader 的“找不到 provider”通常就能从模糊现象落到一个具体模块或描述符。