jjwt 库从 0.9 升级到 0.11 版本 API 变动怎么适配？

核心结论：JJWT 从 0.9.1 升级到 0.11.2 版本后，约 80% 的现有代码会因 parseClaimsJws 方法签名变更而出现编译错误，必须调整依赖配置和代码调用方式。

原因分析

JJWT 在 0.10.0 版本进行了架构巨变，从单一 JAR 包拆分为三个核心模块：jjwt-api（定义接口与抽象类）、jjwt-impl（提供默认实现）、jjwt-jackson（支持 JSON 序列化）。0.9.1 及之前版本只需引入一个依赖io.jsonwebtoken:jjwt:0.9.1，而 0.11.2 版本必须同时引入三个模块且版本号严格保持一致。最典型的报错信息为：错误：找不到符号符号：方法 parseClaimsJws(java.lang.String) 位置：接口 io.jsonwebtoken.JwtParserBuilder。这是因为 0.11.x 版本中parseClaimsJws(String)方法被重构，需要先调用setSigningKey()配置密钥后再解析。

解决方案

2.1 修改 Maven 依赖配置

删除原有的 0.9.1 依赖，替换为以下三个模块（版本号必须均为 0.11.2）：

<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-api</artifactId>
  <version>0.11.2</version>
</dependency>
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-impl</artifactId>
  <version>0.11.2</version>
  <scope>runtime</scope>
</dependency>
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-jackson</artifactId>
  <version>0.11.2</version>
  <scope>runtime</scope>
</dependency>

执行mvn dependency:tree | grep jsonwebtoken命令检查依赖树，确保没有旧版本 0.9.1 残留。

2.2 代码迁移示例

0.9.1 版本的典型代码：

Claims claims = Jwts.parser()
  .setSigningKey(secret)
  .parseClaimsJws(token)
  .getBody();

0.11.2 版本的正确写法：

Claims claims = Jwts.parserBuilder()
  .setSigningKey(key)
  .build()
  .parseClaimsJws(token)
  .getBody();

注意密钥类型变更：0.9.x 允许直接使用 String 类型密钥，0.11.x 推荐使用java.security.Key对象，可通过io.jsonwebtoken.security.Keys工具类生成。

2.3 清理本地 Maven 仓库

删除本地仓库中的旧版本缓存：rm -rf ~/.m2/repository/io/jsonwebtoken/jjwt/0.9*，然后执行mvn clean compile重新构建项目。

注意事项

1. 依赖冲突问题：Spring Boot 2.3.x 早期版本可能通过 spring-security-oauth2 传递性引入 JJWT 0.9.1，需使用<exclusions>排除旧依赖。

2. 密钥强度要求：0.11.x 版本对 HS256 算法要求密钥至少 256 位，使用短字符串密钥会抛出WeakKeyException异常。

3. 序列化兼容性：若项目使用 Gson 而非 Jackson，需将jjwt-jackson替换为jjwt-gson模块，否则可能出现DecodingException: Illegal base64 character错误。

4. 运行时异常风险：即使编译通过，若 jjwt-api 与 jjwt-impl 版本不一致（如 api 用 0.11.5 而 impl 用 0.10.8），运行时会抛出NoSuchMethodError或AbstractMethodError。

参考来源

来源：CSDN 博客 - 别再被 JJWT 新版坑了！手把手教你从 0.12.x 降级到 0.11.2 解决 parseClaimsJws 报错

来源：知乎技术专栏 - JJWT 版本升级陷阱：从 parseClaimsJws 报错看 JJWT API 的演进与兼容性

来源：Maven Central - io.jsonwebtoken:jjwt-api:0.11.2 依赖文档

来源：GitHub Issue - JJWT 0.10.0 模块化拆分说明