基于 JJWT 0.13.0 API 的正确代码示例和 Ma ven 依赖。
确认 Ma ven 依赖
动手之前，第一步永远是确认依赖。请务必检查你的 pom.xml，确保使用了正确的配置。从 JJWT 0.13.0 版本开始，库采用了更清晰的模块化架构，依赖项也相应拆分。
io.jsonwebtoken jjwt-api 0.13.0 io.jsonwebtoken jjwt-impl 0.13.0 runtime io.jsonwebtoken jjwt-jackson 0.13.0 runtime
这里有个关键点需要注意：根据公开的依赖更新日志，0.13.0 版本确实存在，但社区的主流文档和示例目前大多仍围绕更成熟的 0.11.x 系列。在 0.11.5 中，Jwts.parserBuilder() 就已经是官方推荐的标准用法了。如果你确定要使用 0.13.0，其核心 API 设计理念与 0.11.x 基本一致，但稳妥起见，强烈建议查阅其官方发布说明，以确认是否有任何细微但重要的变更。
使用新 API 的 JWT 工具类
理解了依赖，接下来就是实战。下面这个工具类示例，完全基于最新的 parserBuilder() 风格 API 构建，可以直接拿来参考或集成。
首先，是一个简单的配置类，用于集中管理 JWT 相关参数：
public class SecurityProperties {
private JwtConfig jwt = new JwtConfig();
/**
* JWT密钥 - 至少32字节（256位）用于HMAC-SHA算法
*/
private String secret;
/**
* JWT过期时间（秒）
*/
private Long expiration = 86400L;
/**
* JWT刷新过期时间（秒）
*/
private Long refreshExpiration = 604800L;
/**
* JWT签发者
*/
private String issuer = "you-system";
/**
* JWT受众
*/
private String audience = "you-client";
/**
* JWT令牌前缀
*/
private String tokenPrefix = "Bearer";
}
}
然后是核心的工具类，包含了令牌的生成与解析：
import io.jsonwebtoken.*;
import io.jsonwebtoken.security.Keys;
import ja vax.crypto.SecretKey;
import ja va.util.Date;
import ja va.util.Map;
public class JwtUtil {
private final SecretKey secretKey;
private final long expirationMs;
public JwtUtil(SecretKey secretKey, long expirationMs) {
this.secretKey = secretKey;
this.expirationMs = expirationMs;
}
/**
* 生成JWT令牌
*
* @param subject 主题（如用户ID）
* @param claims 自定义声明（载荷）
* @return 生成的JWT字符串
*/
public String generateToken(String subject, Map claims) {
long nowMillis = System.currentTimeMillis();
Date now = new Date(nowMillis);
Date exp = new Date(nowMillis + expirationMs);
// 过期方法
// JwtBuilder builder = Jwts.builder()
// .setSubject(subject)
// .setIssuedAt(now)
// .setExpiration(exp)
// .signWith(secretKey); // 直接使用SecretKey对象
String refreshTokenIssuer = securityProperties.getJwt().getIssuer() + "-refresh";
// 替换方法
JwtBuilder builder = Jwts.builder().claims(claims)
.subject(subject)
.issuedAt(toDate(now))
.expiration(toDate(expirationTime))
.issuer(refreshTokenIssuer) // 设置刷新令牌签发者
.audience().add(securityProperties.getJwt().getAudience()).and() // 使用配置的受众
.signWith(getSecretKey(), Jwts.SIG.HS512); // 使用HS512算法签名
if (claims != null) {
builder.setClaims(claims);
}
// 压缩生成最终令牌
return builder.compact();
}
/**
* 解析并验证JWT令牌（使用新API Jwts.parserBuilder()）
*
* @param token 待解析的JWT字符串
* @return 解析出的声明（Claims）
* @throws JwtException 如果令牌无效、过期或签名验证失败
*/
public Claims parseToken(String token) throws JwtException {
// 过时方法
// return Jwts.parserBuilder() // 使用新的parserBuilder
// .setSigningKey(secretKey) // 设置签名密钥
// .build() // 构建不可变的、线程安全的JwtParser实例
// .parseClaimsJws(token) // 解析并验证JWT
// .getBody(); // 获取载荷（Claims）
// 替换方法
return Jwts.parser()
.verifyWith(getSecretKey())
.build()
.parseSignedClaims(token)
.getPayload();
}
}
密钥生成与管理
安全是 JWT 的基石，而密钥管理则是安全的核心。上面的工具类使用了 ja vax.crypto.SecretKey 对象，那么如何安全地生成和保管它呢？JJWT 提供了非常便捷的工具类。
import io.jsonwebtoken.security.Keys;
import ja vax.crypto.SecretKey;
import ja va.util.Base64;
public class KeyGenerator {
public static void main(String[] args) {
// 为HS256算法生成一个安全的密钥 SignatureAlgorithm.HS256 过时替换 Jwts.SIG.HS512
SecretKey key = Keys.secretKeyFor(Jwts.SIG.HS512);
// 如果需要将密钥以字符串形式保存（如存储在配置文件中），可以编码为Base64
String base64Key = Base64.getEncoder().encodeToString(key.getEncoded());
System.out.println("Base64 encoded key: " + base64Key);
// 在应用启动时，可以从Base64字符串重新构造SecretKey
// byte[] decodedKey = Base64.getDecoder().decode(base64Key);
// SecretKey originalKey = new SecretKeySpec(decodedKey, 0, decodedKey.length, "HmacSHA256");
}
}
这里必须敲一下黑板：在生产环境中，密钥绝不允许硬编码在源代码里。务必从安全的配置源获取，例如环境变量、专业的密钥管理服务（如 AWS KMS, HashiCorp Vault）或加密的配置文件。这是防止密钥泄露的生命线。
如何使用工具类
工具类和密钥都准备好了，怎么用呢？下面是一个完整的演示流程，从初始化到生成再到解析验证，一目了然。
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.security.Keys;
import ja vax.crypto.SecretKey;
import ja va.util.HashMap;
import ja va.util.Map;
public class Application {
public static void main(String[] args) {
// 1. 生成密钥（在实际应用中，这个密钥应该来自安全配置）
SecretKey secretKey = Keys.secretKeyFor(Jwts.SIG.HS512);
long expirationMs = 24 * 60 * 60 * 1000; // 24小时
// 2. 初始化JWT工具类
JwtUtil jwtUtil = new JwtUtil(secretKey, expirationMs);
// 3. 准备自定义声明
Map claims = new HashMap<>();
claims.put("userId", 1001);
claims.put("role", "admin");
// 4. 生成JWT令牌
String subject = "user123";
String jwtToken = jwtUtil.generateToken(subject, claims);
System.out.println("Generated JWT: " + jwtToken);
// 5. 解析和验证JWT令牌
try {
Claims parsedClaims = jwtUtil.parseToken(jwtToken);
System.out.println("Token subject: " + parsedClaims.getSubject());
System.out.println("User ID from token: " + parsedClaims.get("userId", Integer.class));
} catch (JwtException e) {
System.err.println("JWT validation failed: " + e.getMessage());
}
}
}
核心变更与总结
最后，我们来梳理一下这次升级或新上手需要把握的几个核心要点：
- API 设计更清晰：新的
JwtParser通过 Builder 模式构建，产生的实例是不可变且线程安全的，这符合现代 API 设计的最佳实践。 - 密钥安全升级：强烈推荐使用
io.jsonwebtoken.security.Keys工具类来生成强随机性的SecretKey对象，这比手动处理字符串密钥更安全、更规范。 - 依赖结构模块化：务必检查并正确配置你的依赖，确保同时引入了
jjwt-api（接口）、jjwt-impl（运行时实现）以及序列化支持（如jjwt-jackson）。
希望这份基于最新 API 的指南，能帮助你平滑地完成 JWT 相关的开发或升级工作。如果在密钥管理策略或具体的异常处理场景中遇到更深层次的问题，相关的社区讨论和官方文档总是最好的延伸阅读材料。
