一、什么是 JWTJWTJSON Web Token是一种开放标准RFC 7519用于在各方之间安全地传输信息。它由三部分组成Header头部包含令牌类型和签名算法如{alg: HS256, typ: JWT}Payload载荷存放实际要传递的数据如用户ID、角色、过期时间等Signature签名对前两部分进行签名防止数据被篡改JWT 通常用于身份验证和授权特别是在前后端分离的 Web 应用中。二、Hutool JWT 工具类简介Hutool 是一个 Java 工具类库提供了丰富的工具方法。其中cn.hutool.jwt.JWTUtil是专门用于 JWT 生成和验证的工具类它封装了 JWT 的创建、签名、验证等操作让开发者无需关心底层细节。主要特点支持多种签名算法HS256、HS384、HS512、RS256 等链式调用API 设计简洁自动处理时间戳和过期时间支持自定义载荷数据提供完整的验证机制三、快速开始3.1 添加依赖首先需要在项目中引入 Hutool 依赖!-- Maven -- dependency groupIdcn.hutool/groupId artifactIdhutool-all/artifactId version5.8.25/version /dependency3.2 生成 JWT使用 HS256 算法生成一个简单的 JWTimport cn.hutool.jwt.JWT; import cn.hutool.jwt.JWTUtil; public class JwtDemo { public static void main(String[] args) { // 设置密钥 byte[] key my-secret-key.getBytes(); // 创建 JWT 载荷 MapString, Object payload new HashMap(); payload.put(userId, 12345); payload.put(username, zhangsan); payload.put(role, admin); // 生成 JWT默认使用 HS256 算法 String token JWTUtil.createToken(payload, key); System.out.println(生成的 JWT: token); } }3.3 验证 JWT验证 JWT 的有效性和解析数据import cn.hutool.jwt.JWT; import cn.hutool.jwt.JWTUtil; public class JwtDemo { public static void main(String[] args) { String token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...; byte[] key my-secret-key.getBytes(); // 验证 JWT boolean verify JWTUtil.verify(token, key); System.out.println(验证结果: verify); // 解析 JWT JWT jwt JWTUtil.parseToken(token); System.out.println(用户ID: jwt.getPayload(userId)); System.out.println(用户名: jwt.getPayload(username)); System.out.println(角色: jwt.getPayload(role)); } }四、高级用法4.1 设置过期时间JWT 通常需要设置过期时间以保证安全性import cn.hutool.jwt.JWT; import cn.hutool.jwt.JWTUtil; import cn.hutool.jwt.signers.JWTSignerUtil; public class JwtDemo { public static void main(String[] args) { byte[] key my-secret-key.getBytes(); // 创建 JWT 并设置过期时间30分钟后过期 MapString, Object payload new HashMap(); payload.put(userId, 12345); payload.put(exp, System.currentTimeMillis() / 1000 1800); // 30分钟 String token JWTUtil.createToken(payload, key); System.out.println(带过期时间的 JWT: token); } }4.2 使用其他签名算法Hutool 支持多种签名算法import cn.hutool.jwt.JWT; import cn.hutool.jwt.JWTUtil; import cn.hutool.jwt.signers.JWTSignerUtil; public class JwtDemo { public static void main(String[] args) { // HS512 算法 byte[] key my-secret-key.getBytes(); String token1 JWTUtil.createToken(payload, key, JWTSignerUtil.hs512(key)); // 使用 RSA 算法需要公钥私钥 // String privateKey ...; // String token2 JWTUtil.createToken(payload, JWTSignerUtil.rs256(privateKey)); } }4.3 自定义 Header可以自定义 JWT 的 Header 信息import cn.hutool.jwt.JWT; import cn.hutool.jwt.JWTUtil; public class JwtDemo { public static void main(String[] args) { byte[] key my-secret-key.getBytes(); MapString, Object headers new HashMap(); headers.put(alg, HS512); headers.put(typ, JWT); headers.put(kid, key-id-001); MapString, Object payload new HashMap(); payload.put(userId, 12345); // 创建 JWT 时指定 Header JWT jwt JWT.create() .setHeader(headers) .setPayload(payload) .setKey(key); String token jwt.sign(); System.out.println(自定义 Header 的 JWT: token); } }五、实际应用场景5.1 用户登录认证在用户登录成功后生成 JWT 返回给客户端RestController RequestMapping(/auth) public class AuthController { PostMapping(/login) public Result login(RequestBody LoginRequest request) { // 1. 验证用户名密码 User user userService.authenticate(request); // 2. 生成 JWT MapString, Object payload new HashMap(); payload.put(userId, user.getId()); payload.put(username, user.getUsername()); payload.put(role, user.getRole()); payload.put(exp, System.currentTimeMillis() / 1000 3600); // 1小时过期 String token JWTUtil.createToken(payload, SECRET_KEY.getBytes()); // 3. 返回给客户端 return Result.success(登录成功, token); } }5.2 接口权限验证使用拦截器验证 JWTComponent public class JwtInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { String token request.getHeader(Authorization); if (token null || !token.startsWith(Bearer )) { response.setStatus(401); return false; } token token.substring(7); // 去掉 Bearer 前缀 // 验证 JWT if (!JWTUtil.verify(token, SECRET_KEY.getBytes())) { response.setStatus(401); return false; } // 解析用户信息 JWT jwt JWTUtil.parseToken(token); request.setAttribute(userId, jwt.getPayload(userId)); request.setAttribute(role, jwt.getPayload(role)); return true; } }六、jwt工具import cn.hutool.jwt.JWT; import cn.hutool.jwt.JWTUtil; import cn.hutool.jwt.JWTValidator; import cn.hutool.jwt.signers.JWTSigner; import cn.hutool.jwt.signers.JWTSignerUtil; import cn.hutool.core.util.StrUtil; import java.util.Date; import java.util.HashMap; import java.util.Map; import java.util.UUID; /** * Hutool JWT 工具类 * * author YourName * date 2026-08-01 */ public class JwtUtils { /** * 秘钥实际使用时请从配置文件读取 */ private static final String SECRET your-secret-key-please-change-in-production; /** * 签发者 */ private static final String ISSUER your-app-name; /** * 默认有效期毫秒默认7天 */ private static final long DEFAULT_EXPIRE_TIME 7 * 24 * 60 * 60 * 1000L; /** * 创建JWT签名器使用HS256算法 */ private static final JWTSigner SIGNER JWTSignerUtil.hs256(SECRET.getBytes()); /** * 生成JWT Token * * param userId 用户ID * param username 用户名 * return JWT Token字符串 */ public static String generateToken(String userId, String username) { return generateToken(userId, username, DEFAULT_EXPIRE_TIME); } /** * 生成JWT Token自定义有效期 * * param userId 用户ID * param username 用户名 * param expireTime 过期时间毫秒 * return JWT Token字符串 */ public static String generateToken(String userId, String username, long expireTime) { Date now new Date(); Date expireDate new Date(now.getTime() expireTime); MapString, Object payload new HashMap(16); // 标准字段 payload.put(sub, userId); payload.put(iss, ISSUER); payload.put(iat, now.getTime() / 1000); payload.put(exp, expireDate.getTime() / 1000); payload.put(jti, UUID.randomUUID().toString()); // 自定义字段 payload.put(userId, userId); payload.put(username, username); return JWTUtil.createToken(payload, SIGNER); } /** * 解析JWT Token * * param token JWT Token字符串 * return JWT对象 */ public static JWT parseToken(String token) { if (StrUtil.isBlank(token)) { throw new IllegalArgumentException(Token不能为空); } return JWTUtil.parseToken(token); } /** * 验证JWT Token是否有效包含过期验证 * * param token JWT Token字符串 * return true: 有效, false: 无效 */ public static boolean verifyToken(String token) { if (StrUtil.isBlank(token)) { return false; } try { JWT jwt parseToken(token); // 验证签名 boolean verified jwt.verify(SIGNER); if (!verified) { return false; } // 验证有效期 JWTValidator.of(jwt).validateDate(); return true; } catch (Exception e) { return false; } } /** * 验证JWT Token并返回ClaimsMap形式 * * param token JWT Token字符串 * return Claims Map */ public static MapString, Object verifyAndGetClaims(String token) { if (!verifyToken(token)) { throw new IllegalArgumentException(Token无效或已过期); } return getClaims(token); } /** * 获取Token的所有Claims不验证有效期 * * param token JWT Token字符串 * return Claims Map */ public static MapString, Object getClaims(String token) { JWT jwt parseToken(token); MapString, Object claims new HashMap(); // 直接获取payload并转换为Map Object payload jwt.getPayload(); if (payload instanceof Map) { claims.putAll((Map? extends String, ?) payload); } return claims; } /** * 从Token中获取指定字段值 * * param token JWT Token字符串 * param key 字段名 * return 字段值 */ public static Object getClaim(String token, String key) { JWT jwt parseToken(token); return jwt.getPayload(key); } /** * 从Token中获取用户ID * * param token JWT Token字符串 * return 用户ID */ public static String getUserId(String token) { Object userId getClaim(token, userId); return userId ! null ? userId.toString() : null; } /** * 从Token中获取用户名 * * param token JWT Token字符串 * return 用户名 */ public static String getUsername(String token) { Object username getClaim(token, username); return username ! null ? username.toString() : null; } /** * 从Token中获取主题用户ID * * param token JWT Token字符串 * return 主题 */ public static String getSubject(String token) { Object sub getClaim(token, sub); return sub ! null ? sub.toString() : null; } /** * 获取Token的签发时间 * * param token JWT Token字符串 * return 签发时间 */ public static Date getIssuedAt(String token) { Object iat getClaim(token, iat); if (iat null) { return null; } long timestamp Long.parseLong(iat.toString()) * 1000; return new Date(timestamp); } /** * 获取Token的过期时间 * * param token JWT Token字符串 * return 过期时间 */ public static Date getExpiration(String token) { Object exp getClaim(token, exp); if (exp null) { return null; } long timestamp Long.parseLong(exp.toString()) * 1000; return new Date(timestamp); } /** * 检查Token是否已过期 * * param token JWT Token字符串 * return true: 已过期, false: 未过期 */ public static boolean isExpired(String token) { Date expiration getExpiration(token); if (expiration null) { return true; } return expiration.before(new Date()); } /** * 获取Token剩余有效时间毫秒 * * param token JWT Token字符串 * return 剩余时间毫秒负数表示已过期 */ public static long getRemainingTime(String token) { Date expiration getExpiration(token); if (expiration null) { return -1; } return expiration.getTime() - System.currentTimeMillis(); } /** * 刷新Token重新生成有效期重置 * * param oldToken 旧的Token * return 新的Token */ public static String refreshToken(String oldToken) { if (!verifyToken(oldToken)) { throw new IllegalArgumentException(Token无效或已过期无法刷新); } String userId getUserId(oldToken); String username getUsername(oldToken); return generateToken(userId, username); } /** * 刷新Token自定义有效期 * * param oldToken 旧的Token * param expireTime 新的过期时间毫秒 * return 新的Token */ public static String refreshToken(String oldToken, long expireTime) { if (!verifyToken(oldToken)) { throw new IllegalArgumentException(Token无效或已过期无法刷新); } String userId getUserId(oldToken); String username getUsername(oldToken); return generateToken(userId, username, expireTime); } /** * 从Token中获取签发者 * * param token JWT Token字符串 * return 签发者 */ public static String getIssuer(String token) { Object iss getClaim(token, iss); return iss ! null ? iss.toString() : null; } /** * 从Token中获取JWT ID * * param token JWT Token字符串 * return JWT ID */ public static String getJwtId(String token) { Object jti getClaim(token, jti); return jti ! null ? jti.toString() : null; } }测试用例public class JwtUtilsTest { public static void main(String[] args) { // 1. 生成Token String token JwtUtils.generateToken(10001, 张三); System.out.println(生成的Token: token); // 2. 验证Token boolean isValid JwtUtils.verifyToken(token); System.out.println(Token是否有效: isValid); // 3. 获取用户信息 String userId JwtUtils.getUserId(token); String username JwtUtils.getUsername(token); System.out.println(用户ID: userId); System.out.println(用户名: username); // 4. 获取过期时间 Date expiration JwtUtils.getExpiration(token); System.out.println(过期时间: expiration); // 5. 获取剩余时间 long remaining JwtUtils.getRemainingTime(token); System.out.println(剩余时间(毫秒): remaining); // 6. 刷新Token String newToken JwtUtils.refreshToken(token); System.out.println(刷新后的Token: newToken); // 7. 自定义有效期生成Token1小时 String customToken JwtUtils.generateToken(10002, 李四, 3600000L); System.out.println(自定义有效期Token: customToken); // 8. 解析Token获取所有Claims MapString, Object claims JwtUtils.verifyAndGetClaims(token); System.out.println(Claims: claims); } }建议过期时间秘钥写在配置文件中jwt: secret: your-secret-key-please-change-in-production expire-time: 604800000 # 7天 issuer: your-app-name七、注意事项密钥安全签名密钥需要妥善保管不要硬编码在代码中过期时间一定要设置合理的过期时间避免令牌被长期滥用敏感数据不要在 JWT 中存储敏感信息因为 Payload 可以被 Base64 解码刷新机制考虑实现令牌刷新机制避免用户频繁重新登录算法选择根据安全要求选择合适的签名算法生产环境建议使用 RS256七、总结Hutool 的 JWT 工具类提供了简洁易用的 API让 Java 开发者能够快速实现 JWT 的生成、验证和解析。通过本文的介绍你应该已经掌握了JWT 的基本概念和结构如何使用 Hutool JWTUtil 生成和验证令牌高级功能如设置过期时间、自定义 Header、使用不同算法在实际项目中的应用场景和注意事项Hutool JWT 工具类大大简化了 JWT 相关的开发工作是 Java 项目中处理身份认证的优秀选择。
