Java ResourceBundle 怎样按 Locale 查找并回退资源

如果页面语言来自请求参数、用户设置或租户配置，就不要用无参的 ResourceBundle.getBundle("i18n.Messages") 猜语言。更稳定的做法是把目标 Locale 显式传入，再把地区资源、语言资源和基础资源按层级放好。这样 Java 才能按既定候选关系查找，找不到更具体的文件时再回退。

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

下面用 i18n.Messages 作为资源基名，围绕“指定 Locale、理解回退、确认实际命中”三个容易混淆的点展开。文中的图片是静态结构说明图，不是运行截图或执行结果。

先把资源层级和请求 Locale 对齐

ResourceBundle 的关键不是手工拼接文件名，而是把资源基名和目标 Locale 交给 getBundle。例如，中文繁体台湾场景可以准备下面几层文件：

# 资源文件名示例；同一个 key 可以在更具体的文件中覆盖
i18n/Messages_zh_TW.properties
i18n/Messages_zh.properties
i18n/Messages.properties

调用处明确传入 Locale，业务入口负责决定语言，资源加载负责按规则寻找文件：

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

public class Messages {
    public static String loadTitle(Locale requestedLocale) {
        // 请求 Locale 由业务层传入，避免隐式读取 JVM 的默认语言
        ResourceBundle bundle = ResourceBundle.getBundle(
                "i18n.Messages", requestedLocale);
        // getString 会沿当前 bundle 的父级资源查找同名 key
        return bundle.getString("page.title");
    }
}

这里的边界很重要：Locale 决定查找方向，ResourceBundle 决定资源层级，key 是否存在则是另一件事。把三者混成“文件名不对”会让排查绕远。

默认 Locale 不是请求 Locale 的同义词

如果请求的是 Locale.ITALY，而 JVM 默认 Locale 是法语环境，默认查找会先尝试意大利的候选资源；在更具体资源不存在时，还可能继续尝试默认 Locale 的资源，最后才落到基础资源。也就是说，默认 Locale 是额外的回退来源，不是对请求参数的替换。

因此，下面两种代码表达的意图不同：

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

// 业务已经知道用户语言时，显式传入目标 Locale
ResourceBundle requested = ResourceBundle.getBundle(
        "i18n.Messages", Locale.ITALY);

// 只有确实要跟随 JVM 全局默认语言时，才使用无参重载
ResourceBundle implicit = ResourceBundle.getBundle("i18n.Messages");

在服务端，JVM 默认 Locale 往往由启动参数或宿主环境影响。把它当作租户语言会造成同一个请求在不同机器上命中不同资源。更稳妥的做法是让 HTTP、任务消息或用户配置先解析出 Locale，再传给资源层。

需要禁止默认回退时，明确写出控制策略

有些程序只允许“请求 Locale 的候选链 + 基础资源”，不接受 JVM 默认 Locale 插入中间。这时可以使用不提供 fallback Locale 的控制器：

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

public class StrictMessages {
    public static ResourceBundle load(Locale locale) {
        // 只保留请求 Locale 的候选链，不把 JVM 默认 Locale 当额外语言
        ResourceBundle.Control control =
                ResourceBundle.Control.getNoFallbackControl(
                        ResourceBundle.Control.FORMAT_DEFAULT);
        // 该重载适用于 classpath 风格的资源加载场景
        return ResourceBundle.getBundle("i18n.Messages", locale, control);
    }
}

这不是“禁止所有回退”：更具体的 Messages_zh_TW 仍然可以回退到 Messages_zh 和 Messages。它只是不再从请求链跳到 Locale.getDefault() 的另一条链。若项目使用命名模块，要按模块版 getBundle API 和模块资源布局处理，不能直接把 classpath 控制器重载照搬过去。

用 getLocale 判断实际命中，再区分缺失键

调用成功并不代表命中了请求 Locale 对应的文件。ResourceBundle 提供 getLocale()，可以用它记录实际 bundle 的 Locale；读取 key 时则要单独处理 MissingResourceException：

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

public class BundleLookup {
    public static String read(Locale locale, String key) {
        ResourceBundle bundle = ResourceBundle.getBundle("i18n.Messages", locale);
        // 记录实际命中的 Locale，便于区分目标资源与回退资源
        Locale actualLocale = bundle.getLocale();
        try {
            // key 缺失与 Locale 回退是两类问题，分别处理
            return actualLocale + ":" + bundle.getString(key);
        } catch (MissingResourceException ex) {
            // 保留业务上下文后再交给上层决定降级或报错
            throw new IllegalStateException("missing message key: " + key, ex);
        }
    }
}

排查时按这张清单看就够了：基名是否对应资源包路径；目标 Locale 是否由请求显式传入；更具体的文件是否真的位于类路径或模块资源中；默认 Locale 是否被误当成业务配置；最终 getLocale() 是否符合预期；最后才检查具体 key。

常见问题

ResourceBundle 找不到文件时应该先改文件名吗？ 不要先改。先确认基名使用点、包路径和 Locale 候选层级，再检查资源是否被打进运行时 classpath 或模块。文件名只差语言、地区或脚本片段时，应先按候选规则判断缺哪一层。

为什么明明传了 Locale，结果还是像默认语言？ 可能是请求 Locale 的更具体文件不存在，随后回退到默认 Locale 或基础资源。用 getLocale() 记录实际返回值，并根据是否允许跨到默认 Locale 选择普通控制器或无 fallback 控制器。

一句话总结：显式传入目标 Locale，按“地区/语言/基础”准备资源，知道默认 Locale 是否参与回退，并用 getLocale() 观察实际命中；这样本地化资源的问题就从猜文件名变成了可解释的查找规则。