Java ResourceBundle.Control 怎样自定义资源文件的加载顺序

如果同一套 Java 国际化资源需要把某个地区优先回退到另一个地区，核心不是手动拼文件名，而是覆盖 ResourceBundle.Control#getCandidateLocales。它返回的候选 Locale 列表决定当前目标的查找范围，并参与已找到资源的父级关系；找不到整条候选链后，才由 getFallbackLocale 决定是否换一个默认 Locale 继续查找。

官方资料：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/ResourceBundle.html

要自定义“资源文件加载顺序”，优先改 getCandidateLocales；要控制失败后的下一次地区尝试，才改 getFallbackLocale。候选列表通常以 Locale.ROOT 收尾，这样基础资源才有明确的终点。

• getCandidateLocales：定义当前目标 Locale 的候选链与父级关系。
• getFallbackLocale：整条候选链没有结果时，决定是否换 Locale 再找。
• getFormats、getTimeToLive、needsReload：分别处理资源格式和缓存，不会改变候选 Locale 顺序。

为什么要覆盖 getCandidateLocales

默认策略会从更具体的地区逐步回退。例如请求 zh-HK 时，常见链条是 zh-HK、zh、ROOT。若业务希望港区优先复用繁体中文资源，就可以显式返回 zh-HK、zh-TW、ROOT。资源文件名仍按标准命名，例如 Messages_zh_TW.properties 和 Messages.properties。

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

final class HongKongControl extends ResourceBundle.Control {
    @Override
    public List getCandidateLocales(String baseName, Locale locale) {
        // 先校验资源基名，避免把错误输入静默转换成回退结果。
        if (baseName == null || locale == null) {
            throw new NullPointerException("baseName and locale");
        }
        // 港区优先使用台湾繁体资源，ROOT 保留基础资源的最终回退位置。
        if (locale.equals(Locale.forLanguageTag("zh-HK"))) {
            return List.of(locale, Locale.TRADITIONAL_CHINESE, Locale.ROOT);
        }
        // 其他地区沿用默认候选链，避免扩大定制规则的影响范围。
        return super.getCandidateLocales(baseName, locale);
    }
}

ResourceBundle bundle = ResourceBundle.getBundle(
        "Messages",
        Locale.forLanguageTag("zh-HK"),
        new HongKongControl() // 使用自定义候选 Locale 规则
);

这里的“顺序”是候选关系，不应被理解成已经执行过的运行截图。API 会根据候选 Locale 和格式组合寻找资源；具体文件存在与否仍取决于 classpath、模块开放范围和资源命名。

getFallbackLocale、格式与缓存不要混在一起

getCandidateLocales 解决“当前 Locale 先看哪些候选”。如果这些候选都没有得到结果，getFallbackLocale 才负责下一次搜索。例如应用的默认界面语言是英语，可以让失败的中文请求再尝试 en；这不是把 en 塞进所有中文候选链的理由。

final class EnglishFallbackControl extends ResourceBundle.Control {
    @Override
    public Locale getFallbackLocale(String baseName, Locale locale) {
        // 对英文请求不再回退，避免默认 Locale 与当前目标互相循环。
        Locale english = Locale.ENGLISH;
        if (locale.equals(english)) {
            return null;
        }
        // 当前候选链完全没有资源时，再尝试英语资源。
        return english;
    }
}

final class PropertiesOnlyControl extends ResourceBundle.Control {
    @Override
    public List getFormats(String baseName) {
        // 只允许 properties 格式，减少 class 资源与配置文件之间的歧义。
        return List.of("java.properties");
    }
}

资源格式由 getFormats 控制；缓存是否长期保留由 getTimeToLive 决定，缓存过期后是否重新加载则交给 needsReload。修改这些方法不会自动改变 Locale 候选链，最好把每个职责拆成清晰的 Control 实现。

四个容易让回退结果失真的边界

因此，排查“明明有资源却没有按预期加载”时，可以按这条顺序问：目标 Locale 返回了什么候选链？文件名是否对应？是否有基础 ROOT 资源？整条候选链失败后是否又触发了默认 Locale？最后再看格式、缓存和模块可见性。

常见问题

只想改变地区回退顺序，必须重写 newBundle 吗？

通常不需要。只改变候选 Locale 时重写 getCandidateLocales 即可；只有资源格式、实例化方式或文件命名约定也发生变化时，才考虑其他回调。

把默认 Locale 直接放进候选列表可以吗？

可以表达某种业务规则，但它和 getFallbackLocale 的职责不同。若默认语言只应在当前候选链完全失败后尝试，应该使用 getFallbackLocale，避免父级资源关系被意外扩大。

为什么自定义 Control 在模块化项目里不工作？

Java SE API 对 named module 中接受 ResourceBundle.Control 的部分 getBundle 调用有使用限制，可能抛出 UnsupportedOperationException。这时应检查模块化国际化方案，而不是继续堆叠候选 Locale。