【阶段 5】安全与认证：Spring Security 与 JWT

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>security-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>security-demo</name>

    <properties>
        <java.version>17</java.version>
        <jjwt.version>0.12.5</jjwt.version>
        <mybatis-plus.version>3.5.7</mybatis-plus.version>
    </properties>

    <dependencies>
        <!-- Web：Controller / Filter 基础 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Security：认证授权核心 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>

        <!-- OAuth2 客户端：第 5 章接入 GitHub -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-oauth2-client</artifactId>
        </dependency>

        <!-- 参数校验：@Valid / @NotBlank -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>

        <!-- Redis：JWT 黑名单 + 登录限流 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>

        <!-- MyBatis-Plus（Spring Boot 3 专用 starter） -->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
            <version>${mybatis-plus.version}</version>
        </dependency>

        <!-- MySQL 驱动（版本由 Boot 托管） -->
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <scope>runtime</scope>
        </dependency>

        <!-- JWT：API / 实现 / Jackson 序列化 -->
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-api</artifactId>
            <version>${jjwt.version}</version>
        </dependency>
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-impl</artifactId>
            <version>${jjwt.version}</version>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-jackson</artifactId>
            <version>${jjwt.version}</version>
            <scope>runtime</scope>
        </dependency>

        <!-- Lombok：@Data / @Slf4j / @RequiredArgsConstructor -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.security</groupId>
            <artifactId>spring-security-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

-- 用户表：密码列只存 BCrypt 哈希，绝不存明文
CREATE TABLE sys_user (
    id          BIGINT       NOT NULL AUTO_INCREMENT COMMENT '主键',
    username    VARCHAR(64)  NOT NULL COMMENT '登录名，唯一',
    password    VARCHAR(100) NOT NULL COMMENT 'BCrypt 哈希，不是明文',
    nickname    VARCHAR(64)  DEFAULT NULL COMMENT '昵称',
    email       VARCHAR(128) DEFAULT NULL COMMENT '邮箱',
    status      TINYINT      NOT NULL DEFAULT 1 COMMENT '1=启用 0=禁用',
    created_at  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    UNIQUE KEY uk_username (username)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统用户';

-- 角色表
CREATE TABLE sys_role (
    id          BIGINT      NOT NULL AUTO_INCREMENT,
    role_code   VARCHAR(64) NOT NULL COMMENT '角色编码，如 ADMIN / USER',
    role_name   VARCHAR(64) NOT NULL COMMENT '角色展示名',
    description VARCHAR(255) DEFAULT NULL,
    PRIMARY KEY (id),
    UNIQUE KEY uk_role_code (role_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='角色';

-- 权限表：权限粒度比角色更细，如 user:delete
CREATE TABLE sys_permission (
    id          BIGINT      NOT NULL AUTO_INCREMENT,
    perm_code   VARCHAR(64) NOT NULL COMMENT '权限编码，如 user:delete',
    perm_name   VARCHAR(64) NOT NULL,
    description VARCHAR(255) DEFAULT NULL,
    PRIMARY KEY (id),
    UNIQUE KEY uk_perm_code (perm_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='权限';

-- 用户-角色 关联表（多对多）
CREATE TABLE sys_user_role (
    user_id BIGINT NOT NULL,
    role_id BIGINT NOT NULL,
    PRIMARY KEY (user_id, role_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户角色关联';

-- 角色-权限 关联表（多对多）
CREATE TABLE sys_role_permission (
    role_id       BIGINT NOT NULL,
    permission_id BIGINT NOT NULL,
    PRIMARY KEY (role_id, permission_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='角色权限关联';

-- 两个测试用户（密码都是明文 123456，BCrypt 哈希在代码里生成后替换）
INSERT INTO sys_user (username, password, nickname, status) VALUES
('admin', '$2a$10$REPLACE_WITH_BCRYPT', '管理员', 1),
('alice', '$2a$10$REPLACE_WITH_BCRYPT', '普通用户', 1);

INSERT INTO sys_role (role_code, role_name) VALUES ('ADMIN', '管理员'), ('USER', '普通用户');
INSERT INTO sys_permission (perm_code, perm_name) VALUES
('user:create', '新增用户'), ('user:update', '修改用户'), ('user:delete', '删除用户'), ('user:query', '查询用户');

-- admin 拥有 ADMIN 角色；alice 拥有 USER 角色
INSERT INTO sys_user_role (user_id, role_id) VALUES (1, 1), (2, 2);
-- ADMIN 角色拥有全部权限
INSERT INTO sys_role_permission (role_id, permission_id) VALUES
(1, 1), (1, 2), (1, 3), (1, 4);

server:
  port: 8080

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/security_demo?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: ${DB_USERNAME:root}
    password: ${DB_PASSWORD:root}
    driver-class-name: com.mysql.cj.jdbc.Driver
  data:
    redis:
      host: ${REDIS_HOST:localhost}
      port: ${REDIS_PORT:6379}

mybatis-plus:
  mapper-locations: classpath:/mapper/*.xml   # XML 映射文件位置
  configuration:
    map-underscore-to-camel-case: true        # 下划线转驼峰
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

# JWT 配置：密钥和过期时间都从环境变量注入，禁止硬编码进代码
jwt:
  # 生产环境务必通过环境变量 JWT_SECRET 覆盖；本地开发给个默认值方便跑通
  secret: ${JWT_SECRET:change-me-this-is-a-demo-secret-key-please-override-32bytes-min}
  # access token 有效期（秒），2 小时
  expire-seconds: 7200

public interface Authentication extends Principal, Serializable {
    Collection<? extends GrantedAuthority> getAuthorities(); // 权限列表，如 ROLE_ADMIN
    Object getCredentials();   // 凭证：密码、Token，认证成功后通常置空
    Object getDetails();       // 附加信息：客户端 IP、SessionId 等
    Object getPrincipal();     // 主体：登录用户（可能是 UserDetails 或 userId）
    boolean isAuthenticated(); // 是否已认证
}

// 认证失败 → 401（未登录 / 凭证错误）
// 认证成功但权限不足 → 403（无权限访问）

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;
import org.springframework.security.web.SecurityFilterChain;

/**
 * Spring Security 核心配置（最小可用版）。
 * 说明：这是入门版，仅演示过滤器链的组装方式，
 * 后续章节会逐步替换成数据库用户、JWT 过滤器、统一异常等。
 */
@Configuration
public class SecurityConfig {

    @Bean
    public PasswordEncoder passwordEncoder() {
        // BCrypt：加盐哈希，即使是内存用户也不存明文
        return new BCryptPasswordEncoder();
    }

    // 内存用户：生产环境会替换成数据库加载（第 2 章 UserDetailsService）
    @Bean
    public UserDetailsService userDetailsService(PasswordEncoder encoder) {
        UserDetails admin = User.withUsername("admin")
                .password(encoder.encode("123456"))   // 存哈希，不存明文
                .roles("ADMIN")                        // roles() 自动加 ROLE_ 前缀
                .build();
        // InMemoryUserDetailsManager 是 UserDetailsService 的内存实现
        return new InMemoryUserDetailsManager(admin);
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // 授权规则：按 URL 匹配，注意规则从上到下，先匹配先生效
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll()   // 注册/登录放行
                .anyRequest().authenticated()                   // 其余全部要认证
            )
            // 开启 HTTP Basic：请求头 Authorization: Basic base64(user:pass)
            .httpBasic(basic -> {
            });
        return http.build();
    }
}

# 不带凭证访问 → 401（被 AuthorizationFilter 拦截）
curl -i http://localhost:8080/api/users

# 带凭证访问（-u 会自动生成 Basic 头）→ 200
curl -u admin:123456 http://localhost:8080/api/users

package com.example.demo.config;

import com.example.demo.security.JwtAuthFilter;
import com.example.demo.security.RestAccessDeniedHandler;
import com.example.demo.security.RestAuthenticationEntryPoint;
import lombok.RequiredArgsConstructor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

/**
 * 生产级安全配置：JWT 无状态 + 方法级授权 + 统一 JSON 错误返回。
 */
@Configuration
@EnableWebSecurity
@EnableMethodSecurity          // 开启方法级授权（@PreAuthorize），第 4 章详解
@RequiredArgsConstructor       // 构造器注入，依赖不可变
public class SecurityConfig {

    private final JwtAuthFilter jwtAuthFilter;
    private final RestAuthenticationEntryPoint authenticationEntryPoint;
    private final RestAccessDeniedHandler accessDeniedHandler;

    @Bean
    public PasswordEncoder passwordEncoder() {
        // BCrypt：加盐哈希、不可逆、自带慢哈希防暴力破解（第 2 章详解）
        return new BCryptPasswordEncoder();
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // 前后端分离 + JWT 无状态，关闭 CSRF（第 6 章解释为什么是安全的）
            .csrf(csrf -> csrf.disable())
            // 无状态：不创建、不使用 HttpSession
            .sessionManagement(sm -> sm.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            // 授权规则
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll()   // 注册/登录放行
                .requestMatchers("/error").permitAll()          // Spring 默认错误页放行
                .anyRequest().authenticated()                   // 其余都要认证
            )
            // 认证异常 → 401 JSON；授权异常 → 403 JSON（统一前端处理）
            .exceptionHandling(ex -> ex
                .authenticationEntryPoint(authenticationEntryPoint)
                .accessDeniedHandler(accessDeniedHandler)
            )
            // 关键：把 JWT 过滤器插在用户名密码过滤器之前
            .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class);
        return http.build();
    }
}

// 1. 你自己 new 了线程（异步任务），ThreadLocal 不会自动传递
new Thread(() -> {
    // 这里拿不到主线程的 SecurityContext！需要手动传递
    SecurityContext context = SecurityContextHolder.getContext(); // 空
}).start();

// 2. 异步场景可用 DelegatingSecurityContextExecutor 或显式传递
//    或在 @Async 方法里用 SecurityContextHolder.getContext() 前先手动 set

// 最小可用：看懂 BCrypt 的两个核心方法
PasswordEncoder encoder = new BCryptPasswordEncoder();

// 编码：同一个明文，每次结果都不同（因为盐不同）
String h1 = encoder.encode("123456"); // $2a$10$Nk7...每次不同
String h2 = encoder.encode("123456"); // $2a$10$Ab3...和 h1 不同

// 校验：matches(明文, 哈希) 判断是否匹配
boolean ok = encoder.matches("123456", h1);   // true
boolean bad = encoder.matches("654321", h1);  // false

import lombok.Data;
import org.slf4j.MDC;

@Data
public class ApiResult<T> {
    private int code;        // 0=成功，非 0=错误码
    private String message;  // 提示信息
    private T data;          // 业务数据
    private String traceId;  // 链路追踪 id

    public static <T> ApiResult<T> ok(T data) {
        ApiResult<T> r = new ApiResult<>();
        r.setCode(ErrorCode.SUCCESS.getCode());
        r.setMessage(ErrorCode.SUCCESS.getMessage());
        r.setData(data);
        r.setTraceId(MDC.get("traceId"));
        return r;
    }
    public static <T> ApiResult<T> ok() {
        return ok(null);
    }
    public static <T> ApiResult<T> fail(int code, String message) {
        ApiResult<T> r = new ApiResult<>();
        r.setCode(code);
        r.setMessage(message);
        r.setTraceId(MDC.get("traceId"));
        return r;
    }
    public static <T> ApiResult<T> fail(ErrorCode ec) {
        return fail(ec.getCode(), ec.getMessage());
    }
}

package com.example.demo.common;

/**
 * 统一错误码枚举。基础码必须与全系列保持一致，
 * 本篇按安全场景扩展 TOKEN_EXPIRED / TOKEN_INVALID / LOGIN_ERROR。
 */
public enum ErrorCode {
    SUCCESS(0, "success"),
    PARAM_ERROR(40001, "参数错误"),
    UNAUTHORIZED(40101, "未登录或登录已过期"),
    TOKEN_EXPIRED(40102, "登录已过期，请重新登录"),
    TOKEN_INVALID(40103, "无效的令牌"),
    LOGIN_ERROR(40104, "用户名或密码错误"),
    FORBIDDEN(40301, "无权限访问"),
    USER_NOT_FOUND(40401, "用户不存在"),
    SYSTEM_ERROR(50000, "系统繁忙，请稍后重试");

    private final int code;
    private final String message;

    ErrorCode(int code, String message) {
        this.code = code;
        this.message = message;
    }

    public int getCode() {
        return code;
    }

    public String getMessage() {
        return message;
    }
}

package com.example.demo.exception;

import com.example.demo.common.ErrorCode;

/**
 * 统一业务异常：业务代码主动抛出，由全局异常处理器统一转成 ApiResult。
 */
public class BizException extends RuntimeException {
    private final int code;

    public BizException(ErrorCode ec) {
        super(ec.getMessage());
        this.code = ec.getCode();
    }

    public BizException(int code, String message) {
        super(message);
        this.code = code;
    }

    public int getCode() {
        return code;
    }
}

package com.example.demo.exception;

import com.example.demo.common.ApiResult;
import com.example.demo.common.ErrorCode;
import lombok.extern.slf4j.Slf4j;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

/**
 * 全局异常处理器：把各种异常统一转成 ApiResult。
 * 兜底异常对外只返回模糊提示，详细堆栈只进日志（防止泄露内部实现细节）。
 */
@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {

    // 业务异常：直接透出错误码与提示
    @ExceptionHandler(BizException.class)
    public ApiResult<Void> handleBiz(BizException e) {
        log.warn("业务异常: code={}, message={}", e.getCode(), e.getMessage());
        return ApiResult.fail(e.getCode(), e.getMessage());
    }

    // 参数校验异常（@Valid 触发）：提示第一条校验错误
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ApiResult<Void> handleValid(MethodArgumentNotValidException e) {
        String msg = e.getBindingResult().getFieldErrors().stream()
                .findFirst()
                .map(f -> f.getField() + " " + f.getDefaultMessage())
                .orElse(ErrorCode.PARAM_ERROR.getMessage());
        return ApiResult.fail(ErrorCode.PARAM_ERROR.getCode(), msg);
    }

    // 授权异常：@PreAuthorize 校验失败时抛出，统一返回 403
    @ExceptionHandler(AccessDeniedException.class)
    public ApiResult<Void> handleAccessDenied(AccessDeniedException e) {
        log.warn("越权访问被拦截: {}", e.getMessage());
        return ApiResult.fail(ErrorCode.FORBIDDEN);
    }

    // 兜底异常：对外模糊提示，详细堆栈进日志
    @ExceptionHandler(Exception.class)
    public ApiResult<Void> handleOther(Exception e) {
        log.error("系统异常", e);
        return ApiResult.fail(ErrorCode.SYSTEM_ERROR);
    }
}

package com.example.demo.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;

import java.time.LocalDateTime;

/**
 * 系统用户实体，映射 sys_user 表。
 * 注意：password 列存的是 BCrypt 哈希，不是明文。
 */
@Data
@TableName("sys_user")
public class SysUser {
    @TableId(type = IdType.AUTO)
    private Long id;
    private String username;
    private String password;   // BCrypt 哈希
    private String nickname;
    private String email;
    private Integer status;    // 1=启用 0=禁用
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}

package com.example.demo.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.example.demo.entity.SysUser;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

/**
 * 用户数据访问层。BaseMapper 已提供 selectById / insert 等基础方法，
 * 这里补充按用户名查询（登录时需要）。
 */
@Mapper
public interface UserMapper extends BaseMapper<SysUser> {

    // 使用 #{} 预编译占位，防止 SQL 注入（第 6 章详解）
    SysUser selectByUsername(@Param("username") String username);
}

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.example.demo.mapper.UserMapper">

    <!-- 用 #{} 而不是 ${}：预编译参数，防 SQL 注入 -->
    <select id="selectByUsername" resultType="com.example.demo.entity.SysUser">
        SELECT * FROM sys_user WHERE username = #{username}
    </select>

</mapper>

package com.example.demo.security;

import com.example.demo.entity.SysUser;
import lombok.Data;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.UserDetails;

import java.util.Collection;
import java.util.List;

/**
 * 实现 UserDetails：Spring Security 认识的「登录用户」。
 * 把 SysUser 包装成 Security 需要的形态，携带权限列表。
 */
@Data
public class LoginUser implements UserDetails {

    private final Long id;
    private final String username;
    private final String password;      // BCrypt 哈希
    private final List<SimpleGrantedAuthority> authorities;
    private final Integer status;       // 1=启用 0=禁用

    /**
     * 从数据库实体构造。authorities 由调用方传入（角色转成 ROLE_xxx）。
     */
    public LoginUser(SysUser user, List<SimpleGrantedAuthority> authorities) {
        this.id = user.getId();
        this.username = user.getUsername();
        this.password = user.getPassword();
        this.status = user.getStatus();
        this.authorities = authorities;
    }

    @Override
    public Collection<? extends GrantedAuthority> getAuthorities() {
        return authorities;
    }

    @Override
    public String getPassword() {
        return password;
    }

    @Override
    public String getUsername() {
        return username;
    }

    // 以下四个「账号状态」方法：生产环境可接入真实的锁定/过期/禁用逻辑
    @Override
    public boolean isAccountNonExpired() {
        return true;
    }

    @Override
    public boolean isAccountNonLocked() {
        return true;
    }

    @Override
    public boolean isCredentialsNonExpired() {
        return true;
    }

    @Override
    public boolean isEnabled() {
        // status == 1 才允许登录
        return status != null && status == 1;
    }
}

package com.example.demo.service;

import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import com.example.demo.common.ErrorCode;
import com.example.demo.entity.SysUser;
import com.example.demo.exception.BizException;
import com.example.demo.mapper.UserMapper;
import com.example.demo.security.LoginUser;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.stereotype.Service;

import java.util.List;

/**
 * 从数据库加载用户，供 Spring Security 认证使用。
 * 说明：登录失败统一抛「用户名或密码错误」，这里不区分用户是否存在，
 * 防止攻击者通过错误提示探测哪些用户名是真实存在的（防撞库）。
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class UserDetailsServiceImpl implements UserDetailsService {

    private final UserMapper userMapper;

    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        SysUser user = userMapper.selectOne(
                Wrappers.<SysUser>lambdaQuery().eq(SysUser::getUsername, username));
        if (user == null) {
            // 不抛「用户不存在」，而是抛统一的认证失败，避免泄露用户是否存在
            log.info("登录失败：用户名 {} 不存在", username);
            throw new UsernameNotFoundException("用户名或密码错误");
        }
        // 把角色列表转成 Spring Security 的权限对象（ROLE_ 前缀）
        // 这里先给一个默认角色，第 4 章会从 sys_role 表真正查询
        List<SimpleGrantedAuthority> authorities =
                List.of(new SimpleGrantedAuthority("ROLE_USER"));
        return new LoginUser(user, authorities);
    }
}

package com.example.demo.dto;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import lombok.Data;

/**
 * 注册入参。JSR-303 校验，字段约束在进入业务逻辑前就拦截。
 */
@Data
public class RegisterDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 32, message = "用户名长度需在 3~32 之间")
    private String username;

    @NotBlank(message = "密码不能为空")
    @Size(min = 6, max = 64, message = "密码长度需在 6~64 之间")
    private String password;

    private String nickname;
}

package com.example.demo.dto;

import jakarta.validation.constraints.NotBlank;
import lombok.Data;

/**
 * 登录入参。
 */
@Data
public class LoginDTO {
    @NotBlank(message = "用户名不能为空")
    private String username;

    @NotBlank(message = "密码不能为空")
    private String password;
}

package com.example.demo.vo;

import lombok.AllArgsConstructor;
import lombok.Data;

/**
 * 登录出参。第 3 章会加入 token 字段。
 */
@Data
@AllArgsConstructor
public class LoginVO {
    private Long id;
    private String username;
    private String nickname;
}

package com.example.demo.service.impl;

import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import com.example.demo.common.ErrorCode;
import com.example.demo.dto.LoginDTO;
import com.example.demo.dto.RegisterDTO;
import com.example.demo.entity.SysUser;
import com.example.demo.exception.BizException;
import com.example.demo.mapper.UserMapper;
import com.example.demo.security.LoginUser;
import com.example.demo.service.AuthService;
import com.example.demo.vo.LoginVO;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.stereotype.Service;

/**
 * 认证业务：注册（密码 BCrypt 编码）+ 登录（交给 AuthenticationManager 校验）。
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class AuthServiceImpl implements AuthService {

    private final UserMapper userMapper;
    private final PasswordEncoder passwordEncoder;
    private final AuthenticationManager authenticationManager;

    @Override
    public void register(RegisterDTO dto) {
        // 用户名唯一性校验，避免重复注册
        Long count = userMapper.selectCount(
                Wrappers.<SysUser>lambdaQuery().eq(SysUser::getUsername, dto.getUsername()));
        if (count > 0) {
            throw new BizException(ErrorCode.PARAM_ERROR.getCode(), "用户名已存在");
        }
        SysUser user = new SysUser();
        user.setUsername(dto.getUsername());
        // 关键：存库前用 BCrypt 编码，绝不存明文
        user.setPassword(passwordEncoder.encode(dto.getPassword()));
        user.setNickname(dto.getNickname());
        user.setStatus(1);
        userMapper.insert(user);
        log.info("用户注册成功: {}", dto.getUsername());
    }

    @Override
    public LoginVO login(LoginDTO dto) {
        // 构造一个「未认证」的令牌，交给 AuthenticationManager 走完整认证流程
        Authentication authentication;
        try {
            authentication = authenticationManager.authenticate(
                    new UsernamePasswordAuthenticationToken(dto.getUsername(), dto.getPassword()));
        } catch (AuthenticationException e) {
            // 无论「用户不存在」还是「密码错误」，统一抛同一个错误码
            log.info("登录失败: username={}", dto.getUsername());
            throw new BizException(ErrorCode.LOGIN_ERROR);
        }
        // 认证成功，从 principal 取出 LoginUser
        LoginUser loginUser = (LoginUser) authentication.getPrincipal();
        return new LoginVO(loginUser.getId(), loginUser.getUsername(), null);
    }
}

package com.example.demo.controller;

import com.example.demo.common.ApiResult;
import com.example.demo.dto.LoginDTO;
import com.example.demo.dto.RegisterDTO;
import com.example.demo.service.AuthService;
import com.example.demo.vo.LoginVO;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 认证接口：注册 / 登录。路径前缀 /api/auth 已在 SecurityConfig 放行。
 */
@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthController {

    private final AuthService authService;

    @PostMapping("/register")
    public ApiResult<Void> register(@Valid @RequestBody RegisterDTO dto) {
        authService.register(dto);
        return ApiResult.ok();
    }

    @PostMapping("/login")
    public ApiResult<LoginVO> login(@Valid @RequestBody LoginDTO dto) {
        return ApiResult.ok(authService.login(dto));
    }
}

// 在 SecurityConfig 里增加这个 Bean
@Bean
public AuthenticationManager authenticationManager(AuthenticationConfiguration config) throws Exception {
    // 从 Spring 的认证配置里取回默认的 AuthenticationManager
    return config.getAuthenticationManager();
}

// 反例：这样写会被攻击者用于枚举用户名
if (user == null) {
    return ApiResult.fail(40401, "用户不存在");   // ❌ 泄露用户名是否真实存在
}
if (!passwordEncoder.matches(raw, user.getPassword())) {
    return ApiResult.fail(40104, "密码错误");      // ❌ 泄露密码是否错误
}

# 1. 注册（密码会被 BCrypt 编码后入库）
curl -X POST http://localhost:8080/api/auth/register 
  -H "Content-Type: application/json" 
  -d '{"username":"bob","password":"123456","nickname":"Bob"}'

# 2. 登录成功（返回用户信息）
curl -X POST http://localhost:8080/api/auth/login 
  -H "Content-Type: application/json" 
  -d '{"username":"bob","password":"123456"}'

# 3. 登录失败（统一提示「用户名或密码错误」，无论用户名还是密码错）
curl -X POST http://localhost:8080/api/auth/login 
  -H "Content-Type: application/json" 
  -d '{"username":"bob","password":"wrong"}'

// 你可以手动解码验证：Base64Url 解码中间那段
String payload = "eyJzdWIiOiIxIn0"; // 解码后就是 {"sub":"1"}

package com.example.demo.security;

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import javax.crypto.SecretKey;
import java.nio.charset.StandardCharsets;
import java.util.Date;
import java.util.List;
import java.util.UUID;

/**
 * JWT 工具：负责签发（generateToken）与解析（parseToken）。
 * 密钥从配置注入，绝不硬编码。
 */
@Component
public class JwtUtil {

    private final SecretKey key;       // HMAC 签名密钥
    private final long expireSeconds;  // 过期时间（秒）

    public JwtUtil(@Value("${jwt.secret}") String secret,
                   @Value("${jwt.expire-seconds}") long expireSeconds) {
        // 密钥外部化：从 application.yml / 环境变量读取，禁止写死在代码里
        // HMAC-SHA256 要求密钥至少 256 bit（32 字节）
        this.key = Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8));
        this.expireSeconds = expireSeconds;
    }

    /**
     * 签发 token。
     * @param userId   用户主键，放在标准声明 sub 里
     * @param username 用户名，放在自定义声明里
     * @param roles    角色编码列表，放在自定义声明里（注意：不要放密码等敏感信息）
     */
    public String generateToken(Long userId, String username, List<String> roles) {
        Date now = new Date();
        Date expiration = new Date(now.getTime() + expireSeconds * 1000L);
        return Jwts.builder()
                .id(UUID.randomUUID().toString())        // jti：令牌唯一 id，供黑名单使用
                .subject(String.valueOf(userId))          // sub：标准声明，存用户主键
                .claim("username", username)              // 自定义声明
                .claim("roles", roles)                    // 自定义声明：角色列表
                .issuedAt(now)                            // iat：签发时间
                .expiration(expiration)                   // exp：过期时间
                .signWith(key)                            // 用密钥签名（默认 HS256）
                .compact();
    }

    /**
     * 解析并校验 token。验签失败、过期都会抛异常，由调用方捕获。
     */
    public Claims parseToken(String token) {
        return Jwts.parser()
                .verifyWith(key)      // 用同一个密钥验签
                .build()
                .parseSignedClaims(token)  // 验签 + 校验 exp
                .getPayload();
    }
}

# application.yml —— 本地开发给默认值，生产用环境变量覆盖
jwt:
  secret: ${JWT_SECRET:change-me-this-is-a-demo-secret-key-please-override-32bytes-min}
  expire-seconds: ${JWT_EXPIRE_SECONDS:7200}

# 生产环境通过环境变量注入真实密钥
export JWT_SECRET="$(openssl rand -base64 48)"   # 生成足够长、随机的密钥
export JWT_EXPIRE_SECONDS=7200

package com.example.demo.security;

import com.example.demo.common.ErrorCode;
import com.example.demo.exception.BizException;
import io.jsonwebtoken.Claims;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.util.List;

/**
 * JWT 认证过滤器：每个请求执行一次，从 Authorization 头解析 token 并放进 SecurityContext。
 * 继承 OncePerRequestFilter，保证单个请求只过滤一次（避免转发/包含导致重复执行）。
 */
@Slf4j
@Component
@RequiredArgsConstructor
public class JwtAuthFilter extends OncePerRequestFilter {

    private final JwtUtil jwtUtil;
    private final TokenBlacklistService blacklistService;

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain)
            throws ServletException, IOException {

        String header = request.getHeader("Authorization");
        // 标准格式：Authorization: Bearer <token>
        if (header != null && header.startsWith("Bearer ")) {
            String token = header.substring(7);   // 去掉 "Bearer " 前缀
            try {
                Claims claims = jwtUtil.parseToken(token);   // 验签 + 校验过期

                // 登出黑名单校验：如果该 jti 已被加入黑名单，视为无效
                if (blacklistService.isBlacklisted(claims.getId())) {
                    throw new BizException(ErrorCode.TOKEN_INVALID);
                }

                // 从 payload 取出用户标识和角色
                Long userId = Long.valueOf(claims.getSubject());
                List<String> roles = claims.get("roles", List.class);
                List<SimpleGrantedAuthority> authorities = roles.stream()
                        .map(r -> new SimpleGrantedAuthority("ROLE_" + r))
                        .toList();

                // 构造已认证的令牌：principal 放 userId，供 @PreAuthorize("#id == authentication.principal") 使用
                UsernamePasswordAuthenticationToken authentication =
                        new UsernamePasswordAuthenticationToken(userId, null, authorities);
                authentication.setDetails(
                        new WebAuthenticationDetailsSource().buildDetails(request));

                // 关键：放进 SecurityContext，后续 AuthorizationFilter 才能看到认证信息
                SecurityContextHolder.getContext().setAuthentication(authentication);
            } catch (Exception e) {
                // 验签失败 / 过期 / 黑名单 / 格式错误：统一清空上下文
                // 不在这里直接返回 401，而是放行给下游，由 AuthenticationEntryPoint 统一返回 401 JSON
                log.debug("JWT 解析失败: {}", e.getMessage());
                SecurityContextHolder.clearContext();
            }
        }
        // 无论如何都继续走链（放行匿名请求），授权交给后续过滤器判断
        filterChain.doFilter(request, response);
    }
}

package com.example.demo.security;

import com.example.demo.common.ApiResult;
import com.example.demo.common.ErrorCode;
import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.stereotype.Component;

import java.io.IOException;

/**
 * 未认证（401）统一处理：返回 JSON 而不是默认的重定向到登录页。
 */
@Component
@RequiredArgsConstructor
public class RestAuthenticationEntryPoint implements AuthenticationEntryPoint {

    private final ObjectMapper objectMapper;

    @Override
    public void commence(HttpServletRequest request,
                         HttpServletResponse response,
                         AuthenticationException authException) throws IOException {
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);   // 401
        response.setContentType("application/json;charset=UTF-8");
        response.getWriter().write(objectMapper.writeValueAsString(ApiResult.fail(ErrorCode.UNAUTHORIZED)));
    }
}

package com.example.demo.security;

import com.example.demo.common.ApiResult;
import com.example.demo.common.ErrorCode;
import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.security.web.access.AccessDeniedHandler;
import org.springframework.stereotype.Component;

import java.io.IOException;

/**
 * 已认证但无权限（403）统一处理：返回 JSON。
 */
@Component
@RequiredArgsConstructor
public class RestAccessDeniedHandler implements AccessDeniedHandler {

    private final ObjectMapper objectMapper;

    @Override
    public void handle(HttpServletRequest request,
                       HttpServletResponse response,
                       AccessDeniedException accessDeniedException) throws IOException {
        response.setStatus(HttpServletResponse.SC_FORBIDDEN);     // 403
        response.setContentType("application/json;charset=UTF-8");
        response.getWriter().write(objectMapper.writeValueAsString(ApiResult.fail(ErrorCode.FORBIDDEN)));
    }
}

package com.example.demo.security;

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Service;

import java.time.Duration;

/**
 * JWT 登出黑名单：用 Redis 存已注销 token 的 jti，实现「主动失效」。
 * 原理：登出时把 jti 写入 Redis，TTL 设为 token 剩余有效期；
 * 过滤器校验时若命中黑名单，视为 token 已失效。
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class TokenBlacklistService {

    private static final String KEY_PREFIX = "jwt:blacklist:";

    private final StringRedisTemplate redisTemplate;

    /**
     * 把 token 加入黑名单。
     * @param jti        token 唯一 id（JwtUtil 里用 UUID 生成）
     * @param expireMillis 该 token 剩余有效时长（毫秒），用于设置 Redis key 的 TTL
     */
    public void blacklist(String jti, long expireMillis) {
        // TTL 到期后 key 自动删除，黑名单不会无限膨胀
        redisTemplate.opsForValue().set(KEY_PREFIX + jti, "1", Duration.ofMillis(expireMillis));
        log.info("token 已加入黑名单: {}", jti);
    }

    /**
     * 判断 jti 是否在黑名单中。
     */
    public boolean isBlacklisted(String jti) {
        if (jti == null) {
            return false;
        }
        return Boolean.TRUE.equals(redisTemplate.hasKey(KEY_PREFIX + jti));
    }
}

// AuthController 增加登出接口
@PostMapping("/logout")
public ApiResult<Void> logout(HttpServletRequest request) {
    String header = request.getHeader("Authorization");
    if (header != null && header.startsWith("Bearer ")) {
        String token = header.substring(7);
        Claims claims = jwtUtil.parseToken(token);
        long remainMillis = claims.getExpiration().getTime() - System.currentTimeMillis();
        if (remainMillis > 0) {
            blacklistService.blacklist(claims.getId(), remainMillis);
        }
    }
    return ApiResult.ok();
}

// LoginVO 增加 token 字段
@Data
@AllArgsConstructor
public class LoginVO {
    private Long id;
    private String username;
    private String nickname;
    private String token;     // 新增：JWT
}

// AuthServiceImpl.login 的结尾改为签发 token 并返回
LoginUser loginUser = (LoginUser) authentication.getPrincipal();
// 从数据库查用户角色（第 4 章会真正实现 role 查询，这里先给默认角色）
List<String> roles = List.of("USER");
String token = jwtUtil.generateToken(loginUser.getId(), loginUser.getUsername(), roles);
return new LoginVO(loginUser.getId(), loginUser.getUsername(), null, token);

.authorizeHttpRequests(auth -> auth
    .requestMatchers("/api/admin/**").hasRole("ADMIN")   // 只有 ADMIN 能访问
    .anyRequest().authenticated())

package com.example.demo.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;

/**
 * 角色实体，映射 sys_role 表。
 */
@Data
@TableName("sys_role")
public class SysRole {
    @TableId(type = IdType.AUTO)
    private Long id;
    private String roleCode;   // 角色编码，如 ADMIN / USER
    private String roleName;   // 角色展示名
    private String description;
}