案例 ICU4J 装了不改 java.text.Collator:SPI 只兜底 JDK 不支持的 locale,78 起已被删

2026-11-17 00:04:41

ICU4J 装了不改 java.text.Collator:SPI 只兜底 JDK 不支持的 locale,78 起已被删

区别于站内 #8099 的 ICU 79 升级清单,这里只看 localespi 与 Collator 这条线:为什么加了 icu4j 依赖排序还是 JDK 的老数据,以及 ICU 78 之后这条链路是怎么断的。

现象:加了 icu4j 依赖,java.text.Collator 还是老排法

典型现场:中文/日文/德文排序在对账、通讯录、搜索建议里不一致,于是往 pom 里加


com.ibm.icu
icu4j

79.1

然后 java.text.Collator.getInstance(Locale.CHINA) 依旧按 JDK 自带数据排。原因不是依赖没生效,是这两套东西本来就不通:ICU4J 的类在 com.ibm.icu.* 下,JDK 的 java.text.Collator 不认识它们,除非中间那层 SPI 装上并且被显式打开。

两条路,只有一条是自动的

做法改的是谁生效条件
直接调 com.ibm.icu.text.Collator你自己的代码加依赖即可
icu4j-localespi(Locale Service Provider)java.text.Collator / DateFormat / BreakIterator 等需要 -Djava.locale.providers 显式包含 SPI,且只兜底

第一道闸:JDK 自己支持的 locale 不会被覆盖

java.util.spi.LocaleServiceProvider 的 javadoc 写得很明确:JDK 的工厂方法先看 JRE 自己支不支持请求的 locale,支持就直接用;不支持才去问已安装 provider 的 isSupportedLocale。

也就是说 SPI 是兜底而不是替换。zh_CN、en_US、de_DE 这些 JRE 都支持,装了 localespi 也轮不到 ICU 出场。ICU 官方文档给的变通是:localespi 在 Locale 的 variant 字段追加后缀(ICU4J 49 起默认 "ICU4J"),getAvailableLocales 里同时列 fr_FR 与 fr_FR_ICU4J,想要 ICU 实现得显式请求 fr_FR_ICU4J。

配置项在 localespi jar 内的 com/ibm/icu/impl/javaspi/ICULocaleServiceProviderConfig.properties:

  • enableIcuVariants 默认 true(是否往 getAvailableLocales 里加带后缀的 locale)
  • icuVariantSuffix 默认 "ICU4J"
  • useDecimalFormat 默认 false(设为 true 时 NumberFormat 返回 DecimalFormat 子类,但 BigInteger/BigDecimal 就不走 ICU 实现)
  • enableIso3Languages 默认 true

这一条决定了:别指望装个 jar 就把全站 java.text.Collator 换成 ICU 排序。要用 ICU 的排序,就直接调 ICU 的类。

第二道闸:java.locale.providers 只在启动时读

localespi 不会自动注册成默认提供者。javadoc 原话是该属性 “read and cached only at the initialization of this class”,要求在 java 启动命令行上给:

java -Djava.locale.providers=SPI,CLDR -jar app.jar

顺序即优先级,SPI 放第一位才会先查 SPI。默认是 CLDR(旧 JDK 是 CLDR,COMPAT),不写 SPI 就不会从 classpath 加载 provider。

在 Spring 的 @PostConstruct 或 ServletContextListener 里 System.setProperty 通常已经晚了;JDK 文档明确不推荐,而且行为还分裂——JDK-8273491 记录的就是“规范说启动后设置无效,实测 OpenJDK 某些组合下又会变”。

所以这项落到运维侧:Tomcat 的 setenv.sh/JAVA_OPTS、K8s 的 JAVA_TOOL_OPTIONS、systemd 的 Environment=。写进 application.yml 没有用。

第三道闸:ICU 78 把 localespi 删了

ICU 77 的发布页就提前公告:从 ICU 78 起计划移除 ICU4J Locale Service Provider(ICU-23071),理由是用途远不如当年、使用量很低、需要为新 Java 版本维护、拖累 ICU4J 开发。ICU 78 发布说明里已经落到“已删除”:

We have removed the ICU4J Locale Service Provider. (ICU-23071) ... Projects that used it should call ICU4J directly instead.

icu4j-localespi 最后一个发布版本是 77.1(ICU 77 页面仍列 Maven com.ibm.icu/icu4j-localespi/77.1)。于是有两件事:

  • 依赖写 icu4j-localespi:78.x 或 79.x 解析不到,构建期就能发现;
  • 从 77 升到 78/79 时,若之前靠 SPI 兜底小众 locale,升级后行为静默回退到 JDK 数据,不报错、不告警。

这是升级时唯一需要主动查的一条:grep java.locale.providers 与 icu4j-localespi。

真用 ICU 的 Collator:freeze 之后才能共享

决定直调 com.ibm.icu.text.Collator 之后,落到第二个坑:线程安全。类注释第一句就是 “A Collator is thread-safe only when frozen”,配套 isFrozen/freeze/cloneAsThawed 来自 Freezable 接口。

private static final Collator CN =
Collator.getInstance(ULocale.SIMPLIFIED_CHINESE).freeze();
  • getInstance 走内部 service cache(源码注释 “fetching from service cache is faster than instantiation”),拿到的实例可能不是你独占的;要改 strength/decomposition 先 clone() 或 cloneAsThawed() 再改。
  • 未冻结的实例跨线程做 compare/getCollationKey,属于对同一对象并发写内部状态,不要这么用。
  • getCollationKey 适合同一个串要反复比较的场景;每次只比一次的,直接 compare 更快(RuleBasedCollator 文档原话)。
  • 排序键与 collator 的 rules、strength、decomposition 绑定,也和 ICU 数据版本绑定。

另有一个移植差异:ICU4J 的 Collator 只支持 canonical 与 no-decomposition 两种,java.text.Collator.FULL_DECOMPOSITION(兼容分解)不支持。从 JDK 迁过来时如果有人设了 FULL,别假设语义等价。

两套 CLDR 同时在场

JDK 打包自己的 CLDR,ICU4J 打包自己的 CLDR,版本不同步:

载体CLDR
JDK 821.0.1
JDK 17 / 1839
JDK 2143
JDK 2547
JDK 2648
ICU 7848
ICU 7949

ICU 79 同时是 Unicode 18 + tzdata 2026e。

于是在一个 JDK 21 进程里,java.text.Collator 用的是 CLDR 43,com.ibm.icu.text.Collator 用的是 ICU 79.1 带的 CLDR 49。中文拼音排序、德文 ö 的位置、标点是否参与比较,都可能给出不同顺序,而且差异只在个别字符上出现,测试用例很容易漏。

如果排序键落了库(把 sort_key 存成列做 ORDER BY),必须把 cldr 版本和 ICU 版本一起存下来;升级 ICU 之后旧键不重建,顺序错乱不会有任何报错。

排查清单

  1. 依赖:grep icu4j、icu4j-charset、icu4j-localespi,确认有没有人还在靠 SPI。
  2. 启动参数:-Djava.locale.providers 是否包含 SPI,SPI 是否在第一位,确认不在代码里 setProperty。
  3. ICU ≥ 78:icu4j-localespi 已不存在,把 java.text.* 的依赖改直调 com.ibm.icu.*。
  4. 共享 Collator:检查有没有 freeze();未冻结实例不要跨线程用。
  5. 落库排序键:带 ICU + CLDR 版本,升级时重建。

项目与文档

复制全文 生成海报 ICU4J ICU i18n 国际化 Java Collator CLDR

推荐文章

程序员茄子在线接单