SpringBoot 2.7.12中JwtBuilder构建Token时如何设置过期时间？

Question

在使用 Spring Boot 2.7.12 构建 JWT Token 时，开发者常遇到如何通过 JwtBuilder 正确设置 Token 过期时间的问题。虽然 JJWT 提供了 `setExpiration(Date exp)` 方法用于指定过期时间，但由于系统时间与 Token 解析时的时区或时间误差，可能导致 Token 提前或延迟失效。此外，部分开发者误用 `setNotBefore(Date nbf)` 或未正确初始化 `expiration` 对象，也会引发 Token 验证异常。如何结合 `java.util.Date` 与 `java.time` API 安全、准确地设置 Token 的有效期，并确保在不同环境下的时间一致性，是实际开发中需要重点关注和调试的问题。

Answer 1

一、理解 JWT Token 的时间设置机制

在使用 Spring Boot 2.7.12 构建 JWT Token 时，开发者常遇到如何通过 JwtBuilder 正确设置 Token 过期时间的问题。JJWT 提供了 setExpiration(Date exp) 方法用于指定过期时间，但系统时间与解析 Token 时的时区或时间误差，可能导致 Token 提前或延迟失效。

JWT 标准中定义了三个与时间相关的字段：

• exp（Expiration Time）：Token 的过期时间。
• nbf（Not Before）：Token 在此时间之前不可用。
• iat（Issued At）：Token 的签发时间。

这些字段本质上都是以 Unix 时间戳（秒数）形式存储的数字，因此必须确保在生成和验证时的时间一致性。

二、时间设置中常见的错误与误区

在实际开发中，开发者常犯以下几类错误：

1. 未正确使用时区：使用 java.util.Date 构造过期时间时，未考虑系统默认时区的影响。
2. 误用 setNotBefore：将 nbf 设置为一个未来时间，导致 Token 刚生成就无法使用。
3. 未使用 java.time API：仍使用过时的 Date 和 Calendar 类，导致时间处理不一致。
4. 未处理系统时间差异：不同服务器之间时间不同步，导致 Token 提前失效或延迟失效。

这些错误会导致 Token 在验证时抛出 ExpiredJwtException 或 InvalidJwtException。

三、使用 java.time 与 java.util.Date 安全地构建 Token

为了确保时间一致性，推荐使用 java.time API 构建时间对象，并将其转换为 java.util.Date 用于 JJWT 的 Token 构建。

以下是一个构建 Token 的示例代码：

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import java.time.Instant;
import java.util.Date;

public class JwtUtil {

    private static final String SECRET_KEY = "your-secret-key";
    private static final long EXPIRATION = 86400000; // 24小时

    public static String generateToken(String subject) {
        Instant now = Instant.now();
        Instant expiration = now.plusMillis(EXPIRATION);
        return Jwts.builder()
                .setSubject(subject)
                .setIssuedAt(Date.from(now))
                .setExpiration(Date.from(expiration))
                .signWith(SignatureAlgorithm.HS512, SECRET_KEY)
                .compact();
    }
}
    

上述代码中，使用了 Instant 来构建时间，并通过 Date.from() 转换为 java.util.Date。这种方式避免了时区问题。

四、时区处理与时间同步机制

时间一致性是构建 JWT Token 的关键。以下是几个推荐做法：

• 统一使用 UTC 时间：在生成和解析 Token 时，使用 UTC 时间作为基准，避免因服务器所在时区不同而产生误差。
• 使用 NTP 同步服务器时间：通过网络时间协议（NTP）确保所有服务器时间一致。
• Token 验证时容忍时间差：某些 JWT 库（如 JJWT）支持设置时间偏移容忍度（clock skew）。

例如，使用 JJWT 验证 Token 时可设置时间偏移：

Jwts.parser()
    .setSigningKey(SECRET_KEY)
    .setAllowedClockSkewSeconds(30) // 容忍 30 秒的时差
    .parseClaimsJws(token);
    

五、调试与排查 Token 时间问题的流程图

当 Token 出现提前失效或验证失败时，可以按照以下流程图进行排查：

graph TD
A[Token验证失败] --> B{是否抛出ExpiredJwtException?}
B -- 是 --> C[检查Token的exp字段]
B -- 否 --> D[检查nbf字段是否设置错误]
C --> E[确认生成Token时的时间是否正确]
E --> F[确认解析Token的服务器时间是否同步]
D --> G[确认nbf时间是否早于当前时间]
F --> H{是否使用UTC时间?}
H -- 是 --> I[继续排查其他问题]
H -- 否 --> J[改用UTC时间生成Token]
    

六、总结性建议与最佳实践

为确保在 Spring Boot 2.7.12 中构建的 JWT Token 时间设置正确，建议遵循以下最佳实践：

实践	说明
使用 java.time API	避免时区问题，确保时间精度。
统一使用 UTC 时间	避免服务器之间因时区不同导致时间误差。
启用 Clock Skew 容忍机制	允许一定的时间偏移，提升系统鲁棒性。
定期同步服务器时间	使用 NTP 确保所有服务器时间一致。
避免误用 nbf 字段	除非必要，否则不要设置 nbf。