Java 21使用JJWT 0.13.0的最新正确用法示例

基于 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 相关的开发或升级工作。如果在密钥管理策略或具体的异常处理场景中遇到更深层次的问题，相关的社区讨论和官方文档总是最好的延伸阅读材料。