Java Locale.forLanguageTag 为什么解析后语言标签变了：规范化、扩展字段与缓存键

线上缓存命中率突然下降时，日志里出现了两组看起来“差不多”的语言键：zh-Hant-TW 和 zh_Hant_TW。排查后发现，问题不在 Redis，而在应用把原始 BCP 47 标签交给 Locale.forLanguageTag 后，又用另一种字符串表示回写缓存键，导致同一个用户请求落到了不同的键上。

Locale 对象应该先统一通过 Locale.forLanguageTag 解析，再用 toLanguageTag() 生成跨系统缓存键；不要把 toString() 的下划线格式当成协议格式，也不要把非法标签被截断后的结果当成原始输入。

影响面：语言相同，缓存为什么仍然分叉

故障表现很具体：同一个用户先请求中文繁体页面，服务从请求头得到 zh-Hant-TW，随后另一个入口把 Locale 调用 toString() 得到 zh_TW_#Hant。如果缓存层把两者直接拼进 i18n: 前缀，它们就是两个不同的字符串。

这不是说两个方法返回了两个 Locale，而是它们承担的用途不同：toString() 兼容 Java 旧式表示，toLanguageTag() 才是面向 BCP 47 的语言标签输出。先把表示格式当成数据契约，后面的定位会清楚很多。

时间线：一次非法标签如何把后半段悄悄丢掉

复现时先保留一个合法标签，再故意在中间放入非法子标签：

import java.util.Locale;

public class LocaleTrace {
    public static void main(String[] args) {
        Locale locale = Locale.forLanguageTag("zh-Hant-TW");
        Locale truncated = Locale.forLanguageTag("zh-Hant-@@-TW");

        System.out.println(locale.toLanguageTag());
        System.out.println(truncated.toLanguageTag());
    }
}

第一行会保留合法的语言、脚本和地区；第二个输入在 @@ 处出现格式问题，也就是遇到了 Ill-formed 子标签，forLanguageTag 会忽略这个非法子标签以及它后面的部分。因此排查日志不能只打印解析后的值，最好同时打印原始请求头，避免把“被截断的结果”误认成用户真实选择。

触发条件：宽松解析和严格校验被混在同一条链路

业务入口通常需要宽容地读取浏览器发送的语言偏好，但配置中心、缓存键生成和数据落库更适合严格校验。把两种意图都交给 forLanguageTag，就会出现“请求没有报错，结果却少了地区”的隐性变化。

如果输入必须完整合法，可以使用 Locale.Builder：

Locale locale = new Locale.Builder()
        .setLanguageTag("zh-Hant-TW")
        .build();

String cacheKey = "i18n:" + locale.toLanguageTag();

Builder.setLanguageTag 对非法标签的处理更严格，会抛出异常。应用可以在边界捕获异常，返回默认语言或记录拒绝原因；一旦进入成功路径，缓存键只从 toLanguageTag() 生成。

根因：两种字符串表示承担了同一个缓存契约

最容易漏掉的是 Unicode 扩展。比如 th-TH-u-nu-thai 不只是“泰语加泰国”，它还表达了数字系统偏好。Oracle 文档说明，Unicode locale extension 的键和值会按规则整理；u-nu-thai 应该作为语言标签的一部分保留下来。

Locale locale = Locale.forLanguageTag("th-TH-u-nu-thai");

String debugValue = locale.toString();
String cacheKey = locale.toLanguageTag();

System.out.println(debugValue);
System.out.println(cacheKey);

这里的 debugValue 只适合日志和调试，cacheKey 才进入跨服务协议。缓存键函数最好只接收已经解析好的 Locale，不要允许调用方传入任意字符串，否则不同入口迟早会重新引入格式分叉。

修复动作：在入口、规范化和缓存层各做一次核对

1. 入口保留原始值：读取 Accept-Language 或配置字段时，把原始字符串放入诊断上下文，不直接拿它拼缓存键。
2. 解析选择策略：用户请求可用 forLanguageTag 做容错解析；强约束配置使用 Builder，捕获异常后明确降级。
3. 统一输出：所有跨服务、数据库和缓存键都调用 toLanguageTag()；toString() 不进入协议字段。
4. 补充扩展测试：至少覆盖 zh-Hant-TW、含 u-nu-thai 的标签、非法子标签和空字符串，并断言原始值与规范化值分别可追踪。

修复后不要只看单次命中率。对同一组输入同时记录原始值、Locale 的语言、脚本、地区和 toLanguageTag() 结果，再核对新旧缓存键是否只保留一套格式。这样才能确认修的是键生成链，而不是碰巧清空了旧缓存。

防复发：把格式差异写成单元测试和接口约定

可以把缓存键生成收口到一个小方法：

static String localeCacheKey(Locale locale) {
    return "i18n:" + locale.toLanguageTag();
}

测试重点不是验证某个 JDK 版本的日志长相，而是验证协议边界：

assert localeCacheKey(Locale.forLanguageTag("zh-Hant-TW"))
        .equals("i18n:zh-Hant-TW");
assert localeCacheKey(Locale.forLanguageTag("th-TH-u-nu-thai"))
        .equals("i18n:th-TH-u-nu-thai");

如果需要把语言标签作为数据库字段或消息字段传递，也沿用同一规则，并在接口文档里写明这是 BCP 47 格式。调试页面可以另外展示 toString()，但字段名要明确，避免下游把它误当成可回传的语言标签。

常见问题

toString() 和 toLanguageTag() 哪个更适合缓存键？

使用 toLanguageTag()。它输出 BCP 47 语言标签，适合协议、URL 参数和跨服务缓存键；toString() 更适合 Java 侧调试展示。

forLanguageTag 遇到非法输入一定会抛异常吗？

不一定。它会在第一个非法子标签处忽略该子标签和后续内容；需要严格失败时，应使用 Locale.Builder.setLanguageTag 并处理异常。

语言标签大小写不同会导致不同 Locale 吗？

解析后 Java 会按语言标签规则输出规范化形式，但应用自己的缓存键仍应统一从同一个 Locale 输出，不能让各入口分别保留原始大小写。

Unicode 扩展可以从缓存键里删掉吗？

只有在业务明确不使用扩展语义时才可以另行设计键。若格式化或数字显示依赖 u-nu-thai 之类的偏好，删除它会把不同结果错误合并。

这次问题的修复点并不复杂：原始标签负责追踪，Locale 负责解析，toLanguageTag() 负责协议输出，Builder 负责严格边界。把这四件事分开，语言标签就不会再以调试字符串的形态悄悄进入缓存系统。