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 8 | 21.0.1 |
| JDK 17 / 18 | 39 |
| JDK 21 | 43 |
| JDK 25 | 47 |
| JDK 26 | 48 |
| ICU 78 | 48 |
| ICU 79 | 49 |
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 之后旧键不重建,顺序错乱不会有任何报错。
排查清单
- 依赖:grep
icu4j、icu4j-charset、icu4j-localespi,确认有没有人还在靠 SPI。 - 启动参数:
-Djava.locale.providers是否包含 SPI,SPI 是否在第一位,确认不在代码里setProperty。 - ICU ≥ 78:
icu4j-localespi已不存在,把java.text.*的依赖改直调com.ibm.icu.*。 - 共享 Collator:检查有没有
freeze();未冻结实例不要跨线程用。 - 落库排序键:带 ICU + CLDR 版本,升级时重建。
项目与文档
- ICU 仓库:https://github.com/unicode-org/icu
- ICU4J 使用说明:https://unicode-org.github.io/icu/userguide/icu4j/
- localespi 文档(已过时,但页面还在):https://unicode-org.github.io/icu/userguide/icu4j/locale-service-provider.html
- ICU 78 发布说明(记录删除,ticket ICU-23071):https://unicode-org.github.io/icu/download/78.html
- ICU 77 发布说明(删除预告):https://unicode-org.github.io/icu/download/77.html
- LocaleServiceProvider javadoc(SPI 兜底顺序与 CLDR/JDK 对照表):https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/spi/LocaleServiceProvider.html
- JDK-8273491:https://bugs.openjdk.org/browse/JDK-8273491
- Maven:https://mvnrepository.com/artifact/com.ibm.icu/icu4j