Java ResourceBundleProvider 怎样在模块化应用中提供多语言资源

如果应用已经迁移到 Java named module，仍然想把多语言资源拆到独立模块，推荐使用 ResourceBundleProvider 配合 ServiceLoader。ResourceBundle.Control 适合 unnamed module 的自定义加载策略，而模块化应用应把“谁提供资源包”声明成服务，让消费者继续通过 ResourceBundle.getBundle 获取资源。

官方地址：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/spi/ResourceBundleProvider.html

这套方案的关键不在于手动调用服务加载器，而在于四个名字必须对得上：资源包的 baseName、spi 服务接口名、提供者实现类以及两个模块里的 uses/provides 声明。下面用一个最小的“订单应用加载中文和英文文案”场景拆开它。

为什么 named module 要换成 ResourceBundleProvider

我第一次把国际化资源拆成独立模块时，直觉是继续覆写 ResourceBundle.Control。这个方向在类路径应用里很自然，但进入 named module 后，控制器并不是推荐的服务扩展点。Oracle 的国际化文档明确把 ResourceBundleProvider 作为模块化场景的替代路径。

可以把职责分成三层：

• 消费者模块只关心 ResourceBundle.getBundle("com.example.order.Messages", locale)。
• SPI 接口约定“这个 baseName 有哪些资源提供者”。
• 提供者模块按 Locale 返回 ResourceBundle，不支持的区域返回 null。

这样拆分后，应用代码与资源包的部署位置解耦。新增一个语言时，通常只需要在提供者模块里增加资源和分支，不必修改消费者模块的查找代码。

先固定 baseName 和服务接口命名

假设资源包的 baseName 是 com.example.order.Messages。服务接口需要放在 baseName 所属包的 spi 子包中，简单名使用 baseName 的简单名加 Provider，也就是 com.example.order.spi.MessagesProvider。

package com.example.order.spi;

import java.util.ResourceBundle;
import java.util.spi.ResourceBundleProvider;

// 服务接口只约束资源包类型，让不同模块可以提供同一个 baseName 的资源。
public interface MessagesProvider extends ResourceBundleProvider {
    // 继承 getBundle(String, Locale)，由提供者决定支持哪些语言。
}

这里不要把接口随意命名成 OrderI18n。服务发现依赖约定的全限定名；接口名、包路径和消费者传给 getBundle 的 baseName 不一致时，代码可以编译，但运行时找不到提供者。

提供者怎样按 Locale 返回资源包

提供者可以继承 AbstractResourceBundleProvider，也可以直接实现接口。为了把区域判断写清楚，下面直接实现接口，并返回两个内存中的 ListResourceBundle。真实项目也可以把资源类或 properties 文件打包进提供者模块。

package com.example.order.provider;

import com.example.order.spi.MessagesProvider;
import java.util.ListResourceBundle;
import java.util.Locale;
import java.util.ResourceBundle;

public final class MessagesProviderImpl implements MessagesProvider {
    @Override
    public ResourceBundle getBundle(String baseName, Locale locale) {
        // 只处理约定的 baseName，避免一个服务误接其它资源包请求。
        if (!"com.example.order.Messages".equals(baseName)) {
            return null;
        }
        // 不支持的语言返回 null，让 ResourceBundle 继续寻找其它提供者或回退资源。
        if (Locale.CHINA.equals(locale) || Locale.SIMPLIFIED_CHINESE.equals(locale)) {
            return new ListResourceBundle() {
                protected Object[][] getContents() {
                    // key 保持稳定，值只承担中文展示文案。
                    return new Object[][] {{"paid", "订单已支付"}};
                }
            };
        }
        if (Locale.US.equals(locale) || Locale.ENGLISH.equals(locale)) {
            return new ListResourceBundle() {
                protected Object[][] getContents() {
                    // 英文资源与中文资源使用同一个 key，便于消费者复用代码。
                    return new Object[][] {{"paid", "Order paid"}};
                }
            };
        }
        return null;
    }
}

这里有一个容易忽略的取舍：提供者返回 null 表示“我不负责这个 Locale”，而不是返回一个空资源包。空资源包会让调用者误以为请求成功，却可能在读取键时得到缺失结果。对于默认语言，最好明确准备基础资源，避免所有提供者都返回 null。

module-info.java 怎样把服务链声明完整

服务接口所在模块需要导出接口包；提供者模块需要声明 provides；消费者模块需要声明 uses。下面分别列出三处声明，重点是服务类型必须使用接口，而不是实现类。

module order.i18n.api {
    // 消费者和提供者都需要看见 SPI 接口。
    exports com.example.order.spi;
    requires java.base;
}

module order.i18n.provider {
    // provider 模块读取 API 模块中的服务接口。
    requires order.i18n.api;

    // 用实现类提供服务，服务类型仍然是 MessagesProvider。
    provides com.example.order.spi.MessagesProvider
        with com.example.order.provider.MessagesProviderImpl;
}

module order.app {
    // getBundle 的模块化查找需要消费者声明使用该服务。
    requires order.i18n.api;
    uses com.example.order.spi.MessagesProvider;
}

如果提供者还使用了 XML、数据库或其它外部资源，先确认这些资源已经作为模块资源打包，并且读取路径与模块内的包名一致。不要把“服务已经注册”和“资源文件一定存在”混成同一个问题。

消费者如何取得中文和英文资源

消费者不需要自行实例化 MessagesProviderImpl，也不需要在业务代码里直接调用 ServiceLoader。使用标准工厂方法即可把模块声明交给 Java 的资源包查找机制。

package com.example.order.app;

import java.util.Locale;
import java.util.ResourceBundle;

public final class OrderLabels {
    public static String paidLabel(Locale locale) {
        // baseName 必须与服务接口命名约定对应。
        ResourceBundle bundle = ResourceBundle.getBundle(
            "com.example.order.Messages", locale);
        // 读取同一个 key，语言差异由提供者模块承担。
        return bundle.getString("paid");
    }
}

部署时要让消费者模块能够解析提供者模块，并确保服务接口的全限定名只对应一个明确的 baseName。多模块都提供同一资源包时，要提前设计语言或区域的分工，避免相同 Locale 出现不可预测的竞争。

常见故障可以按四个检查点排查

特别是 split package：如果多个模块同时把资源放进相同包，模块系统可能先在解析阶段报错，而不是在 getBundle 时才暴露。资源提供者可以按语言或区域把资源安排到不同包中，减少模块之间的包冲突。

什么时候仍然适合使用 ResourceBundle.Control

如果应用仍是 classpath 或 unnamed module，并且确实需要自定义格式、资源命名或缓存策略，ResourceBundle.Control 仍然有价值。它和 ResourceBundleProvider 不是同一个层面的 API：前者改变加载策略，后者解决 named module 中资源服务的发现与部署。

实际迁移时可以按这个顺序做：先保留消费者的 ResourceBundle.getBundle 调用，再把资源加载逻辑移到提供者模块，随后补齐 uses/provides，最后为每个支持的 Locale 添加资源。这样每一步都能单独定位，不会把模块解析问题、服务发现问题和缺少资源键混为一谈。

相关问题

ResourceBundleProvider 必须手动调用 ServiceLoader 吗？

通常不需要。只要模块声明正确，ResourceBundle.getBundle 会使用模块化服务机制查找提供者。直接手动加载会让业务代码重新耦合到提供者实现。

不支持某个 Locale 时应该抛异常吗？

提供者通常返回 null 表示不负责该区域，让资源包机制继续处理。是否最终抛出缺少资源异常，取决于是否存在默认资源和其它可用提供者。

ResourceBundle.Control 和 ResourceBundleProvider 能同时使用吗？

可以在不同部署形态中分别使用，但不要把 named module 的服务发现责任继续交给 Control。先根据模块边界选择入口，再保持消费者调用方式稳定。