// 接口 1：登录
@PostMapping("/login")
public AuthToken login() {
    return new AuthToken("token123", "refresh456");
}

// 接口 2：查询用户
@GetMapping("/user")
public User getUser() {
    return new User(1001L, "admin");
}

package com.example.auth.common.model;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;

/**
 * 统一响应封装
 *
 * 为什么需要统一响应？
 * 1. 前端可以统一处理响应格式
 * 2. 可以通过 code 判断请求是否成功
 * 3. 可以通过 message 展示错误信息
 *
 * @param <T> 数据类型（泛型）
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Result<T> implements Serializable {

    /**
     * 响应码
     * 200 表示成功，其他表示失败
     */
    private Integer code;

    /**
     * 响应消息
     * 成功时可以是 "操作成功"
     * 失败时可以是具体的错误信息
     */
    private String message;

    /**
     * 响应数据
     * 使用泛型，可以是任何类型
     */
    private T data;

    /**
     * 成功响应（带数据）
     *
     * 使用示例：
     * return Result.ok(authToken);
     *
     * @param data 响应数据
     * @return Result 对象
     */
    public static <T> Result<T> ok(T data) {
        return new Result<>(200, "操作成功", data);
    }

    /**
     * 成功响应（不带数据）
     *
     * 使用示例：
     * return Result.ok();
     *
     * @return Result 对象
     */
    public static <T> Result<T> ok() {
        return new Result<>(200, "操作成功", null);
    }

    /**
     * 失败响应
     *
     * 使用示例：
     * return Result.fail(401, "用户名或密码错误");
     *
     * @param code 错误码
     * @param message 错误信息
     * @return Result 对象
     */
    public static <T> Result<T> fail(Integer code, String message) {
        return new Result<>(code, message, null);
    }

    /**
     * 失败响应（默认 500 错误码）
     *
     * 使用示例：
     * return Result.fail("服务器内部错误");
     *
     * @param message 错误信息
     * @return Result 对象
     */
    public static <T> Result<T> fail(String message) {
        return new Result<>(500, message, null);
    }
}

// 接口 1：登录
@PostMapping("/login")
public Result<AuthToken> login() {
    AuthToken token = new AuthToken("token123", "refresh456");
    return Result.ok(token);
}

// 接口 2：查询用户
@GetMapping("/user")
public Result<User> getUser() {
    User user = new User(1001L, "admin");
    return Result.ok(user);
}

package com.example.auth.common.util;

import cn.hutool.core.lang.Snowflake;
import cn.hutool.core.util.IdUtil;

/**
 * 雪花算法 ID 生成器
 *
 * 为什么需要雪花算法？
 * 1. 数据库自增 ID 在分布式环境下会冲突
 * 2. UUID 太长（36 位），且无序，不利于数据库索引
 * 3. 雪花算法生成的 ID 是 Long 类型（19 位），且趋势递增
 */
public class SnowflakeIdGenerator {

    /**
     * Hutool 提供的雪花算法实例
     * 参数说明：
     * - workerId: 工作机器 ID（0-31）
     * - datacenterId: 数据中心 ID（0-31）
     */
    private static final Snowflake SNOWFLAKE = IdUtil.getSnowflake(1, 1);

    /**
     * 生成下一个 ID
     *
     * @return 19 位的 Long 类型 ID
     */
    public static Long nextId() {
        return SNOWFLAKE.nextId();
    }
}

package com.example.auth.web;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * 认证系统启动类
 */
@SpringBootApplication(scanBasePackages = "com.example.auth")
public class AuthApplication {

    public static void main(String[] args) {
        SpringApplication.run(AuthApplication.class, args);
    }
}

package com.example.auth.core.util.crypto;

import lombok.extern.slf4j.Slf4j;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Component;
import org.springframework.util.FileCopyUtils;

import java.io.IOException;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

/**
 * RSA 密钥管理工具类
 * 负责加载和解析 PEM 格式的 RSA 密钥
 */
@Slf4j
@Component
public class RsaKeyManager {

    /**
     * 从 resources 目录读取文件内容
     *
     * 为什么用 ClassPathResource？
     * 因为项目打包成 jar 后，文件会被打包到 jar 包内部，
     * 普通的 File 类无法读取 jar 包内的文件，必须使用 ClassPathResource
     *
     * @param resourcePath 资源路径，例如：certs/public_key.pem
     * @return 文件内容（字符串）
     * @throws IOException 如果文件不存在或读取失败
     */
    public String readResourceFile(String resourcePath) throws IOException {
        // 创建 ClassPathResource 对象，指向 resources 目录下的文件
        ClassPathResource resource = new ClassPathResource(resourcePath);

        // 使用 Spring 提供的 FileCopyUtils 读取文件内容
        // InputStreamReader 用于将字节流转换为字符流，并指定编码为 UTF-8
        try (InputStreamReader reader = new InputStreamReader(resource.getInputStream(), StandardCharsets.UTF_8)) {
            return FileCopyUtils.copyToString(reader);
        }
    }

    /**
     * 加载私钥
     *
     * @param privateKeyPem PEM 格式的私钥字符串
     * @return PrivateKey 对象
     * @throws Exception 如果密钥格式错误或解析失败
     */
    public PrivateKey loadPrivateKey(String privateKeyPem) throws Exception {
        // 步骤 1：清理 PEM 格式的头尾标记
        // 原始内容：
        // -----BEGIN RSA PRIVATE KEY-----
        // MIIEpAIBAAKCAQEA...
        // -----END RSA PRIVATE KEY-----
        //
        // 清理后：
        // MIIEpAIBAAKCAQEA...
        String privateKeyContent = privateKeyPem
                .replace("-----BEGIN RSA PRIVATE KEY-----", "")
                .replace("-----END RSA PRIVATE KEY-----", "")
                .replace("-----BEGIN PRIVATE KEY-----", "")
                .replace("-----END PRIVATE KEY-----", "")
                .replaceAll("\\s", ""); // 去除所有空白字符（空格、换行、制表符）

        // 步骤 2：将 Base64 编码的字符串解码为字节数组
        byte[] keyBytes = Base64.getDecoder().decode(privateKeyContent);

        // 步骤 3：使用 PKCS8 规范解析私钥
        // PKCS8 是一种密钥存储格式标准
        PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(keyBytes);

        // 步骤 4：使用 KeyFactory 生成 PrivateKey 对象
        // "RSA" 表示使用 RSA 算法
        KeyFactory keyFactory = KeyFactory.getInstance("RSA");
        PrivateKey privateKey = keyFactory.generatePrivate(keySpec);

        log.info("私钥加载成功");
        return privateKey;
    }

    /**
     * 加载公钥
     *
     * @param publicKeyPem PEM 格式的公钥字符串
     * @return PublicKey 对象
     * @throws Exception 如果密钥格式错误或解析失败
     */
    public PublicKey loadPublicKey(String publicKeyPem) throws Exception {
        // 步骤 1：清理 PEM 格式的头尾标记
        String publicKeyContent = publicKeyPem
                .replace("-----BEGIN PUBLIC KEY-----", "")
                .replace("-----END PUBLIC KEY-----", "")
                .replaceAll("\\s", ""); // 去除所有空白字符

        // 步骤 2：将 Base64 编码的字符串解码为字节数组
        byte[] keyBytes = Base64.getDecoder().decode(publicKeyContent);

        // 步骤 3：使用 X509 规范解析公钥
        // X509 是公钥证书的标准格式
        X509EncodedKeySpec keySpec = new X509EncodedKeySpec(keyBytes);

        // 步骤 4：使用 KeyFactory 生成 PublicKey 对象
        KeyFactory keyFactory = KeyFactory.getInstance("RSA");
        PublicKey publicKey = keyFactory.generatePublic(keySpec);

        log.info("公钥加载成功");
        return publicKey;
    }
}

// ❌ 旧版本写法（存在隐患）
Jwts.builder()
    .signWith(SignatureAlgorithm.HS256, rsaPrivateKey) // 运行时才会报错！
    .compact();

// ✅ 新版本写法（类型安全）
Jwts.builder()
    .signWith(rsaPrivateKey, Jwts.SIG.RS256) // 编译期检查
    .compact();

package com.example.auth.core.config.properties;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

/**
 * JWT 核心配置类
 * 自动绑定 application.yml 中以 jwt 开头的配置项
 */
@Data
@Component
@ConfigurationProperties(prefix = "jwt")
public class JwtProperties {

    /**
     * 签发者标识 (Issuer)
     * 用于在多系统交互中标识 Token 来源
     */
    private String issuer = "auth-service";

    /**
     * Access Token 有效期（分钟）
     * 默认 15 分钟
     */
    private Integer accessTokenExpireMinutes = 15;

    /**
     * 时钟偏差容忍度（秒）
     * 解决分布式服务器时间不同步问题，默认 30 秒
     */
    private Long clockSkewSeconds = 30L;

    /**
     * 公钥资源路径
     * 例如: certs/public_key.pem
     */
    private String publicKeyResource = "certs/public_key.pem";

    /**
     * 私钥资源路径
     * 例如: certs/private_key.pem
     */
    private String privateKeyResource = "certs/private_key.pem";
}

package com.example.auth.core.util;

import cn.hutool.core.util.IdUtil;
import com.example.auth.core.config.properties.JwtProperties;
import com.example.auth.core.util.crypto.RsaKeyManager;
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.JwtBuilder;
import io.jsonwebtoken.JwtException;
import io.jsonwebtoken.Jwts;
import jakarta.annotation.PostConstruct;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;

import java.security.PrivateKey;
import java.security.PublicKey;
import java.util.Date;
import java.util.Map;

/**
 * JWT 工具类
 * 封装 JJWT 0.12 原生 API，提供开箱即用的 Token 服务
 */
@Component
@Slf4j
@RequiredArgsConstructor
public class JwtUtil {

    private final JwtProperties jwtProperties;
    private final RsaKeyManager rsaKeyManager;

    // 缓存解析后的密钥对象，避免每次请求重复解析 PEM 字符串
    private PrivateKey privateKey;
    private PublicKey publicKey;

    /**
     * 初始化阶段：加载密钥
     * 利用 Spring 生命周期，在应用启动时完成耗时的密钥解析
     */
    @PostConstruct
    public void init() throws Exception {
        // 从文件加载私钥
        String privateKeyContent = rsaKeyManager.readResourceFile(jwtProperties.getPrivateKeyResource());
        this.privateKey = rsaKeyManager.loadPrivateKey(privateKeyContent);

        // 从文件加载公钥
        String publicKeyContent = rsaKeyManager.readResourceFile(jwtProperties.getPublicKeyResource());
        this.publicKey = rsaKeyManager.loadPublicKey(publicKeyContent);

        log.info("JWT 工具类初始化完成: Issuer ={}, Access Token 有效期 ={}分钟",
                jwtProperties.getIssuer(),
                jwtProperties.getAccessTokenExpireMinutes());
    }

    /**
     * 创建 Token
     * 对应原生 API 的 signWith 流程
     *
     * @param userId 用户 ID
     * @param username 用户名
     * @param extraClaims 扩展载荷（如角色、权限），可以为 null
     * @return JWT 字符串
     */
    public String createToken(Long userId, String username, Map <String, Object> extraClaims) {
        // 获取当前时间（毫秒）
        long nowMillis = System.currentTimeMillis();
        Date now = new Date(nowMillis);

        // 计算过期时间：当前时间 + 配置的分钟数
        // 注意：需要先转换为毫秒（1 分钟 = 60 秒 = 60000 毫秒）
        Date expiration = new Date(nowMillis + jwtProperties.getAccessTokenExpireMinutes() * 60 * 1000L);

        // 使用 Hutool 生成 JTI (JWT ID)，用于后续的黑名单功能
        // fastSimpleUUID() 生成的是无连字符的 UUID，性能更高
        String jti = IdUtil.fastSimpleUUID();

        // 开始构建 JWT
        JwtBuilder builder = Jwts.builder()
                // 设置头部类型为 JWT
                .header().type("JWT").and()

                // === 标准声明 (Standard Claims) == =
                // issuer: 签发者，标识这个 Token 是谁发的
                .issuer(jwtProperties.getIssuer())
                // subject: 主题，通常存放用户 ID
                .subject(userId.toString())
                // issuedAt: 签发时间
                .issuedAt(now)
                // expiration: 过期时间
                .expiration(expiration)
                // id: JWT 唯一标识，用于黑名单机制
                .id(jti)

                // === 私有声明 (Private Claims) == =
                // 存放业务相关的自定义字段
                .claim("username", username)
                .claim("userId", userId);

        // 如果有额外的载荷（如角色、权限），则添加进去
        if (extraClaims != null && ! extraClaims.isEmpty()) {
            builder.claims().add(extraClaims);
        }

        // 核心签名：使用 RSA 私钥 + RS256 算法
        // Jwts.SIG.RS256 是 JJWT 0.12 提供的类型安全常量
        return builder.signWith(privateKey, Jwts.SIG.RS256).compact();
    }

    /**
     * 解析并验证 Token
     * 对应原生 API 的 verifyWith 流程
     *
     * @param token JWT 字符串
     * @return Claims 载荷对象，包含所有声明信息
     * @throws JwtException 如果验证失败（过期、签名错误等）
     */
    public Claims parseToken(String token) {
        return Jwts.parser()
                // 指定公钥验证签名
                .verifyWith(publicKey)

                // 设置时钟偏差 (核心细节)
                // 允许两台服务器之间存在 30 秒的时间差
                // 避免刚签发的 Token 因为时间不同步而立即失效
                .clockSkewSeconds(jwtProperties.getClockSkewSeconds())

                // 构建解析器（JJWT 0.12 必须显式调用 build）
                .build()

                // 解析签名后的 Token，并返回载荷部分
                .parseSignedClaims(token)
                .getPayload();
    }

    /**
     * 快速验证方法
     * 吞没异常，仅返回布尔值，适用于过滤器中的快速判断
     *
     * @param token JWT 字符串
     * @return true 表示 Token 有效，false 表示无效
     */
    public boolean validateToken(String token) {
        try {
            parseToken(token);
            return true;
        } catch (JwtException | IllegalArgumentException e) {
            // 这里不打印完整堆栈，避免日志刷屏
            // 只记录简要信息，方便排查问题
            log.debug("Token 验证失败: {}", e.getMessage());
            return false;
        }
    }

    /**
     * 从 Token 中提取用户 ID
     * 这是一个便捷方法，避免每次都要先 parseToken 再 getSubject
     *
     * @param token JWT 字符串
     * @return 用户 ID，如果解析失败则返回 null
     */
    public Long getUserIdFromToken(String token) {
        try {
            Claims claims = parseToken(token);
            // subject 存储的是字符串形式的用户 ID，需要转换为 Long
            return Long.parseLong(claims.getSubject());
        } catch (Exception e) {
            log.warn("从 Token 中提取用户 ID 失败: {}", e.getMessage());
            return null;
        }
    }

    /**
     * 从 Token 中提取用户名
     *
     * @param token JWT 字符串
     * @return 用户名，如果解析失败则返回 null
     */
    public String getUsernameFromToken(String token) {
        try {
            Claims claims = parseToken(token);
            // 从私有声明中获取 username
            return claims.get("username", String.class);
        } catch (Exception e) {
            log.warn("从 Token 中提取用户名失败: {}", e.getMessage());
            return null;
        }
    }

    /**
     * 从 Token 中提取 JTI (JWT ID)
     * 用于黑名单机制
     *
     * @param token JWT 字符串
     * @return JTI，如果解析失败则返回 null
     */
    public String getJtiFromToken(String token) {
        try {
            Claims claims = parseToken(token);
            return claims.getId();
        } catch (Exception e) {
            log.warn("从 Token 中提取 JTI 失败: {}", e.getMessage());
            return null;
        }
    }
}

package com.example.auth.core.service;

import com.example.auth.core.util.JwtUtil;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

/**
 * Token 管理服务
 * 负责令牌的创建、验证等业务逻辑
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class TokenService {

    private final JwtUtil jwtUtil;

    /**
     * 创建令牌（登录成功后调用）
     *
     * @param userId 用户 ID
     * @param username 用户名
     * @return JWT Token 字符串
     */
    public String createToken(Long userId, String username) {
        log.info("开始创建令牌: userId ={}, username ={}", userId, username);

        // 调用 JwtUtil 生成 Token
        String token = jwtUtil.createToken(userId, username, null);

        log.info("令牌创建成功: userId ={}", userId);
        return token;
    }

    /**
     * 验证令牌是否有效
     *
     * @param token JWT Token 字符串
     * @return true 表示有效，false 表示无效
     */
    public boolean validateToken(String token) {
        return jwtUtil.validateToken(token);
    }
}

package com.example.auth.web.controller;

import com.example.auth.common.model.Result;
import com.example.auth.core.service.TokenService;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;

import java.util.HashMap;
import java.util.Map;

/**
 * 认证控制器
 * 提供登录、验证等接口
 */
@Slf4j
@RestController
@RequestMapping("/auth")
@RequiredArgsConstructor
public class AuthController {

    private final TokenService tokenService;

    /**
     * 模拟登录接口
     *
     * 实际业务中应该：
     * 1. 接收用户名和密码
     * 2. 验证密码是否正确
     * 3. 查询用户信息
     * 4. 生成令牌
     *
     * 这里为了演示简化处理，直接生成令牌
     *
     * @param userId 用户 ID
     * @param username 用户名
     * @return 统一响应格式
     */
    @PostMapping("/login")
    public Result <Map<String, Object> > login(@RequestParam Long userId, @RequestParam String username) {
        log.info("收到登录请求: userId ={}, username ={}", userId, username);

        // 生成令牌
        String token = tokenService.createToken(userId, username);

        // 构建响应数据
        Map <String, Object> data = new HashMap <>();
        data.put("token", token);
        data.put("tokenType", "Bearer");

        return Result.ok(data);
    }

    /**
     * 验证令牌接口
     *
     * @param token 访问令牌
     * @return 统一响应格式
     */
    @GetMapping("/validate")
    public Result <Map<String, Object> > validate(@RequestHeader("Authorization") String token) {
        log.info("收到验证令牌请求");

        // 移除 "Bearer " 前缀
        if (token.startsWith("Bearer ")) {
            token = token.substring(7);
        }

        // 验证令牌
        boolean valid = tokenService.validateToken(token);

        // 构建响应数据
        Map <String, Object> data = new HashMap <>();
        data.put("valid", valid);

        return Result.ok(data);
    }
}