ServiceLoader provider怎么配置或排查

我在把一个格式化组件拆成可插拔 provider 时，最容易误判的是：代码能编译，不代表 ServiceLoader 能发现实现。排查时先看运行方式：普通 JAR 走 META-INF/services，显式模块走 uses 与 provides ... with。两条路径都要求服务接口的全限定名、provider 类名和可见性保持一致。

先固定服务接口与 provider 的全限定名

先把服务契约想成一个稳定的插座，provider 是插入的实现。下面的例子故意使用简单接口，方便对照 JAR 内容：

package demo.spi;

// 服务只描述调用契约，不依赖任何具体 provider。
public interface Formatter {
    String format(String input);
}

实现类必须实现接口，类路径模式下通常提供 public 无参构造器：

package demo.provider;

import demo.spi.Formatter;

// provider 保持公开，交给 ServiceLoader 通过无参构造器创建。
public final class UpperCaseFormatter implements Formatter {
    public UpperCaseFormatter() { }

    @Override
    public String format(String input) {
        // 让示例行为稳定，避免把空值处理误当成加载问题。
        return input == null ? "" : input.toUpperCase();
    }
}

按运行方式选择注册载体

如果应用仍在 class path 上运行，在 provider 工程的资源目录创建文件 META-INF/services/demo.spi.Formatter，内容写实现类的全限定名：

demo.provider.UpperCaseFormatter
# 每行一个 provider；注释只用于说明，不要写简单类名

打包后可以用 jar tf provider.jar 看这两个条目是否同时存在：META-INF/services/demo.spi.Formatter 和 demo/provider/UpperCaseFormatter.class。文件要以 UTF-8 保存，文件名不能写成接口的简单名。

如果应用使用显式模块，则在消费方声明服务使用关系，在 provider 模块声明提供关系：

module demo.app {
    // 让模块系统知道本模块会通过 ServiceLoader 使用 Formatter。
    uses demo.spi.Formatter;
}

module demo.provider {
    // provider 包可以保持封装，由模块系统负责定位实现。
    provides demo.spi.Formatter with demo.provider.UpperCaseFormatter;
}

不要把两种注册方式混成一套：模块路径上的 provider 重点看模块描述符，未命名模块则看类加载器找到的配置资源。消费方也不建议直接 requires provider 模块，否则插件替换的意义会被削弱。

用最小加载代码定位发现阶段

provider 是惰性发现和实例化的。只创建 loader 不等于已经创建实现，真正的错误经常在 iterator()、findFirst() 或遍历时出现。排查时先保留最小输出：

import demo.spi.Formatter;
import java.util.ServiceConfigurationError;
import java.util.ServiceLoader;

// 只打印实现类型，先判断“找不到”还是“实例化失败”。
ServiceLoader loader = ServiceLoader.load(Formatter.class);
try {
    for (Formatter formatter : loader) {
        System.out.println(formatter.getClass().getName());
    }
} catch (ServiceConfigurationError error) {
    // 保留原始错误，便于继续检查配置文件和构造器。
    error.printStackTrace();
}

如果循环没有输出且没有异常，通常是没有被当前加载器发现的 provider；如果抛错，才进入配置、加载或实例化分支。需要指定加载器时使用 ServiceLoader.load(Formatter.class, loader)，不要默认假设线程上下文加载器就是你的应用加载器。

对照 ServiceConfigurationError 逐层排查

遇到 ServiceConfigurationError，我会按“资源—类—实例”三层查，而不是先改业务代码：

模块 provider 还有一个容易遗漏的差异：如果 provider 类没有 public static 无参 provider() 方法，就必须本身可赋值给服务类型，并能通过 public 无参构造器创建；如果使用 provider()，它的返回类型必须兼容服务，且方法不能返回 null。每次修改 JAR 后，若复用同一个 loader，还要考虑它的 provider 缓存；调用 reload() 只能清缓存，不能修复错误的注册文件。

打包后的复查清单

• 最终 JAR 中能找到服务接口对应的配置资源，配置文件名不是实现类名。
• 实现类的包名、类名、接口版本与配置文本逐字一致。
• 应用的 ClassLoader 能看见实现类及其运行时依赖。
• 类路径 provider 有 public 无参构造器；模块 provider 的 provides、uses 和 provider() 组合正确。

常见问题

为什么代码编译成功，ServiceLoader 还是空？

编译器不检查 JAR 里的服务配置资源。先检查最终产物是否包含 META-INF/services/服务接口全限定名，再确认使用的 ClassLoader 能看到该 JAR。

provider 一定要 public 吗？

类路径模式要求可加载且可实例化的 provider；模块模式下 provider 类型也要满足公开构造器或公开静态 provider() 的约束。具体错误会在迭代或流处理时暴露。

什么时候应该调用 reload？

只有运行中的 JVM 新增了 provider，才考虑对同一个 loader 调用 reload()。它不会重新解释错误的模块声明，也不会替代重新创建正确的 ClassLoader。