使用Commons Text StringEscapeUtils报NoClassDefFoundError问题

为什么使用Apache Commons Text会抛出Lang3相关类缺失错误 #

• 该报错本质是依赖传递缺失导致的类加载失败，和你代码里直接引入哪个包没有必然关系。
• Apache Commons Text并不是完全独立的自包含组件：其核心的转义处理模块（包括你报错栈中的NumericEntityEscaper、StringEscapeUtils静态初始化逻辑）本身就硬依赖org.apache.commons.lang3包中的基础工具类（比如报错提到的Range）。
• 你当前的运行类路径中只部署了commons-text的jar包，没有同步引入它编译依赖的对应版本commons-lang3jar包，类加载器在初始化Text包的类时，找不到依赖的Lang3类，就会抛出NoClassDefFoundError，哪怕你代码里没有直接调用任何Lang3的API也会触发该错误。
• 常见漏配场景包括：手动拷贝jar包到项目时只拷贝了commons-text的文件、构建打包时配置了依赖排除规则、版本搭配不兼容导致类签名对不上。

问题修复步骤 #

1. 补全匹配版本的依赖 #

• 按照你使用的commons-text版本，引入完全兼容的commons-lang3版本到项目依赖中，不要随意跨大版本搭配：比如常用的Text 1.9版本，需要搭配Lang3 3.12及以上版本，才能保证API签名完全匹配。
• 依赖配置完成后，检查Web应用的部署目录（如Tomcat的WEB-INF/lib路径），确认commons-lang3-xxx.jar真的被打包进入部署包，避免构建过程漏拷依赖。

2. 修正现有编码逻辑的流程错误 #

你当前的代码存在逻辑颠倒问题：先调用escapeJava把原始内容中的τ等特殊字符转成\u03c4格式的Java转义序列，又调用UnicodeUnescaper把这些转义序列反向解码回原始特殊字符，整个流程是无意义的往返转换，完全无法达到预期的编码效果。

• 如果你的目标是实现HTML场景下的特殊字符兼容编码，不需要手动拼接转义、反转的流程，直接调用StringEscapeUtils.escapeHtml4(source)即可：该方法会自动将超出ASCII范围的特殊字符转换为&#XXX;格式的HTML实体，适配全场景浏览器解析。
• 如果你确实需要得到标准Java格式的\uXXXX转义序列，直接调用StringEscapeUtils.escapeJava(source)就可以完成处理，不需要额外叠加UnicodeUnescaper的反转步骤。

内容的提问来源于stack exchange，提问作者Murteza