一、概述

用户认证服务(kb-user-auth)是知识库系统的核心安全模块,负责用户身份认证、JWT Token管理、权限控制等功能。

本文将详细介绍如何从搭建完整的用户登录认证系统,涵盖登录、Token生成与验证、权限校验等核心功能。

1.1 服务定位

用户认证服务作为系统的安全门户,提供:

功能模块说明使用场景
用户登录用户名密码登录、JWT Token生成前端登录获取Token
Token验证JWT Token解析与验证、用户信息获取后续请求携带Token验证身份
权限管理角色权限控制、接口访问控制保护敏感接口
用户管理用户信息查询、密码修改个人中心

1.2 技术架构

kb-user-auth
├── 认证框架:Spring Security 6.x
├── Token生成:JJWT (io.jsonwebtoken:jjwt-api)
├── 数据持久层:MyBatis Plus + MySQL
├── 缓存层:Redis(Token黑名单、登录失败次数)
├── 服务注册:Nacos(服务发现、配置中心)
├── API文档:Knife4j
└── 基础设施:Spring Boot 3.2

1.3 核心流程图

1.3.1 用户登录流程

未命名绘图-第 7 页.drawio.png

1.3.2 Token认证流程

未命名绘图-第 8 页.drawio.png

1.3.3 系统架构图

截屏2026-05-18 18.32.06.png

截屏2026-05-18 18.32.25.png

二、环境准备

2.1 数据库准备

创建用户数据库和相关表:

# 创建数据库
mysql -u root -p -e "CREATE DATABASE kb_user DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 使用数据库
mysql -u root -p kb_user < kb-user-auth/src/main/resources/db/schema.sql

用户表结构(kb\_user):

CREATE TABLE `kb_user` (
  `id` BIGINT NOT NULL COMMENT '用户ID(雪花算法)',
  `username` VARCHAR(50) NOT NULL COMMENT '用户名',
  `password` VARCHAR(255) NOT NULL COMMENT '密码(BCrypt加密)',
  `email` VARCHAR(100) COMMENT '邮箱',
  `phone` VARCHAR(20) COMMENT '手机号',
  `avatar` VARCHAR(500) COMMENT '头像URL',
  `real_name` VARCHAR(50) COMMENT '真实姓名',
  `department` VARCHAR(100) COMMENT '部门',
  `position` VARCHAR(100) COMMENT '岗位',
  `status` TINYINT DEFAULT 1 COMMENT '状态(0-禁用,1-启用)',
  `last_login_time` DATETIME COMMENT '最后登录时间',
  `last_login_ip` VARCHAR(50) COMMENT '最后登录IP',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `create_by` BIGINT COMMENT '创建人',
  `update_by` BIGINT COMMENT '更新人',
  `deleted` TINYINT DEFAULT 0 COMMENT '逻辑删除(0-未删除,1-已删除)',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_username` (`username`),
  KEY `idx_email` (`email`),
  KEY `idx_status` (`status`),
  KEY `idx_deleted` (`deleted`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户表';

-- 初始化测试数据
-- 密码都是123456,使用BCrypt加密后的值
INSERT INTO `kb_user` (`id`, `username`, `password`, `email`, `phone`, `avatar`, `real_name`, `department`, `position`, `status`) VALUES
(1000000000000000001, 'admin', '$2a$10$N.zmdr9k7uOCQb376NoUnuTJ8iAt6Z5EHsM8lE9lBOsl7iAt6Z5EH', 'admin@example.com', '13800138000', 'https://api.dicebear.com/7.x/avataaars/svg?seed=admin', '系统管理员', '技术部', '系统架构师', 1),
(1000000000000000002, 'user', '$2a$10$N.zmdr9k7uOCQb376NoUnuTJ8iAt6Z5EHsM8lE9lBOsl7iAt6Z5EH', 'user@example.com', '13800138001', 'https://api.dicebear.com/7.x/avataaars/svg?seed=user', '普通用户', '产品部', '产品经理', 1),
(1000000000000000003, 'test', '$2a$10$N.zmdr9k7uOCQb376NoUnuTJ8iAt6Z5EHsM8lE9lBOsl7iAt6Z5EH', 'test@example.com', '13800138002', 'https://api.dicebear.com/7.x/avataaars/svg?seed=test', '测试用户', '测试部', '测试工程师', 1);

-- 说明:
-- 1. 上面三个用户的密码都是123456
-- 2. BCrypt加密后的密码是:$2a$10$N.zmdr9k7uOCQb376NoUnuTJ8iAt6Z5EHsM8lE9lBOsl7iAt6Z5EH
-- 3. 如果需要使用其他密码,可以使用在线BCrypt工具生成:https://bcrypt-generator.com/

2.2 依赖配置

pom.xml核心依赖:

文件位置:kb-user-auth/pom.xml

<!-- 公共模块 -->
<dependency>
    <groupId>com.knowledge.base</groupId>
    <artifactId>kb-common</artifactId>
</dependency>
<!-- Spring Boot Web -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Spring Boot Validation -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<!-- Spring Security -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<!-- JWT Token生成 -->
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-api</artifactId>
    <version>0.11.5</version>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-impl</artifactId>
    <version>0.11.5</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-jackson</artifactId>
    <version>0.11.5</version>
    <scope>runtime</scope>
</dependency>
<!-- MySQL驱动 -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>
<!-- Druid数据源 -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>druid-spring-boot-3-starter</artifactId>
    <version>1.2.20</version>
</dependency>
<!-- MyBatis Plus -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.5</version>
</dependency>
<!-- Redis -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
<!-- Nacos配置中心 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>
<!-- Nacos服务发现 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<!-- Hutool -->
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.24</version>
</dependency>
<!-- Lombok -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>
<!-- Knife4j API文档 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

前端package.json依赖:

文件位置:knowledge-base-frontend/package.json

{
  "name": "knowledge-base-frontend",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.20.0",
    "antd": "^5.11.0",
    "@ant-design/icons": "^5.2.6",
    "axios": "^1.6.2",
    "zustand": "^4.4.7",
    "dayjs": "^1.11.10",
    "lodash-es": "^4.17.21"
  },
  "devDependencies": {
    "@types/react": "^18.2.43",
    "@types/react-dom": "^18.2.17",
    "@types/lodash-es": "^4.17.12",
    "@typescript-eslint/eslint-plugin": "^6.14.0",
    "@typescript-eslint/parser": "^6.14.0",
    "@vitejs/plugin-react": "^4.2.1",
    "eslint": "^8.55.0",
    "eslint-plugin-react-hooks": "^4.6.0",
    "eslint-plugin-react-refresh": "^0.4.5",
    "typescript": "^5.2.2",
    "vite": "^5.0.8",
    "less": "^4.2.0"
  }
}

三、核心实现

3.1 JWT Token工具类

JwtTokenUtil.java - 核心功能包括Token生成、验证、解析:

文件位置:kb-common/src/main/java/com/knowledge/base/common/utils/JwtTokenUtil.java

@Slf4j
@Component
public class JwtTokenUtil {

    @Resource
    private JwtConfig jwtConfig;

    /**
     * 生成访问Token
     *
     * @param userId 用户ID
     * @return Token
     */
    public String generateAccessToken(Long userId) {
        return generateToken(userId, jwtConfig.getExpiration() * 1000);
    }

    /**
     * 生成刷新Token
     *
     * @param userId 用户ID
     * @return Token
     */
    public String generateRefreshToken(Long userId) {
        return generateToken(userId, jwtConfig.getRefreshExpiration() * 1000);
    }

    /**
     * 生成Token
     *
     * @param userId 用户ID
     * @param expiration 过期时间(毫秒)
     * @return Token
     */
    private String generateToken(Long userId, Long expiration) {
        Date now = new Date();
        Date expiryDate = new Date(now.getTime() + expiration);

        Map<String, Object> claims = new HashMap<>();
        claims.put("userId", userId);
        claims.put("type", "access");

        return Jwts.builder()
                .claims(claims)
                .subject(String.valueOf(userId))
                .issuer(jwtConfig.getIssuer())
                .issuedAt(now)
                .expiration(expiryDate)
                .signWith(jwtConfig.secretKey())
                .compact();
    }

    /**
     * 解析Token
     *
     * @param token Token
     * @return Claims
     */
    public Claims parseToken(String token) {
        try {
            return Jwts.parser()
                    .verifyWith(jwtConfig.secretKey())
                    .build()
                    .parseSignedClaims(token)
                    .getPayload();
        } catch (Exception e) {
            log.error("解析Token失败:{}", e.getMessage());
            return null;
        }
    }

    /**
     * 从Token中获取用户ID
     *
     * @param token Token
     * @return 用户ID
     */
    public Long getUserIdFromToken(String token) {
        Claims claims = parseToken(token);
        if (claims == null) {
            return null;
        }
        return Long.parseLong(claims.getSubject());
    }

    /**
     * 验证Token是否有效
     *
     * @param token Token
     * @return 是否有效
     */
    public boolean validateToken(String token) {
        try {
            Claims claims = parseToken(token);
            if (claims == null) {
                return false;
            }
            Date expiration = claims.getExpiration();
            return expiration.after(new Date());
        } catch (Exception e) {
            log.error("验证Token失败:{}", e.getMessage());
            return false;
        }
    }

    /**
     * 检查Token是否即将过期
     *
     * @param token Token
     * @param thresholdSeconds 阈值(秒)
     * @return 是否即将过期
     */
    public boolean isTokenExpiringSoon(String token, int thresholdSeconds) {
        try {
            Claims claims = parseToken(token);
            if (claims == null) {
                return true;
            }
            Date expiration = claims.getExpiration();
            long timeToExpiry = expiration.getTime() - System.currentTimeMillis();
            return timeToExpiry < thresholdSeconds * 1000;
        } catch (Exception e) {
            return true;
        }
    }

    /**
     * 刷新Token
     *
     * @param refreshToken 刷新Token
     * @return 新的访问Token
     */
    public String refreshToken(String refreshToken) {
        Claims claims = parseToken(refreshToken);
        if (claims == null) {
            throw new RuntimeException("刷新Token无效");
        }

        Long userId = Long.parseLong(claims.getSubject());
        return generateAccessToken(userId);
    }
}

JwtConfig.java配置类 - JWT配置参数:

文件位置:kb-common/src/main/java/com/knowledge/base/common/config/JwtConfig.java

@Slf4j
@Data
@Configuration
@ConfigurationProperties(prefix = "jwt")
public class JwtConfig {

    /**
     * JWT密钥(Base64编码)
     */
    private String secret = "aW52ZW50ZW1lLWtub3dsZWRnZS1iYXNlLXNlY3JldC1rZXktZm9yLWp3dC10b2tlbi1nZW5lcmF0aW9uLW11c3QtYmUtbG9uZy1lbm91Z2g=";

    /**
     * 访问Token过期时间(秒)
     */
    private int expiration = 7200;

    /**
     * 刷新Token过期时间(秒)
     */
    private int refreshExpiration = 604800;

    /**
     * Token签发者
     */
    private String issuer = "knowledge-base";

    /**
     * 获取签名密钥
     */
    public SecretKey secretKey() {
        byte[] keyBytes = Decoders.BASE64.decode(secret);
        return Keys.hmacShaKeyFor(keyBytes);
    }
}

application.yml配置:

jwt:
  secret: aW52ZW50ZW1lLWtub3dsZWRnZS1iYXNlLXNlY3JldC1rZXktZm9yLWp3dC10b2tlbi1nZW5lcmF0aW9uLW11c3QtYmUtbG9uZy1lbm91Z2g=
  expiration: 7200
  refresh-expiration: 604800
  issuer: knowledge-base

关键点说明:

  • 签名算法:使用HS256(HMAC SHA-256)保证Token安全性
  • Secret密钥:使用Base64编码的长密钥,防止破解
  • Token类型:

    • Access Token:短期有效(2小时),用于API访问
    • Refresh Token:长期有效(7天),用于刷新Access Token
  • Subject:存储用户ID,便于后续查询用户信息

3.2 数据层实现

3.2.1 用户实体类

User.java - 用户实体类:

文件位置:kb-user-auth/src/main/java/com/knowledge/base/userauth/entity/User.java

@Data
@EqualsAndHashCode(callSuper = true)
@TableName("kb_user")
public class User extends BaseEntity {

    /**
     * 用户名
     */
    private String username;

    /**
     * 密码(加密存储)
     */
    private String password;

    /**
     * 邮箱
     */
    private String email;

    /**
     * 手机号
     */
    private String phone;

    /**
     * 头像URL
     */
    private String avatar;

    /**
     * 真实姓名
     */
    private String realName;

    /**
     * 部门
     */
    private String department;

    /**
     * 岗位
     */
    private String position;

    /**
     * 状态(0-禁用,1-启用)
     */
    private Integer status;

    /**
     * 最后登录时间
     */
    private LocalDateTime lastLoginTime;

    /**
     * 最后登录IP
     */
    private String lastLoginIp;

    /**
     * 是否删除(0-否,1-是)
     */
    @TableField(exist = false)
    private Integer isDeleted;
}

BaseEntity.java - 基础实体类:

文件位置:kb-common/src/main/java/com/knowledge/base/common/config/BaseEntity.java

@Data
public abstract class BaseEntity implements Serializable {

    /**
     * 主键ID
     */
    @TableId(type = IdType.ASSIGN_ID)
    private Long id;

    /**
     * 创建时间
     */
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;

    /**
     * 更新时间
     */
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;

    /**
     * 创建人ID
     */
    @TableField(fill = FieldFill.INSERT)
    private Long createBy;

    /**
     * 更新人ID
     */
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private Long updateBy;

    /**
     * 逻辑删除标记(0-未删除,1-已删除)
     */
    @TableLogic
    @TableField(fill = FieldFill.INSERT)
    private Integer deleted;
}

3.2.2 用户Mapper接口

UserMapper.java - 用户Mapper接口:

文件位置:kb-user-auth/src/main/java/com/knowledge/base/userauth/mapper/UserMapper.java

@Mapper
public interface UserMapper extends BaseMapper<User> {

    /**
     * 根据用户名查询用户
     *
     * @param username 用户名
     * @return 用户信息
     */
    User selectByUsername(@Param("username") String username);

    /**
     * 根据邮箱查询用户
     *
     * @param email 邮箱
     * @return 用户信息
     */
    User selectByEmail(@Param("email") String email);

    /**
     * 根据手机号查询用户
     *
     * @param phone 手机号
     * @return 用户信息
     */
    User selectByPhone(@Param("phone") String phone);
}

UserMapper.xml - MyBatis映射文件:

文件位置:kb-user-auth/src/main/resources/mapper/UserMapper.xml

<?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.knowledge.base.userauth.mapper.UserMapper">

    <!-- 通用查询映射结果 -->
    <resultMap id="BaseResultMap" type="com.knowledge.base.userauth.entity.User">
        <id column="id" property="id" />
        <result column="username" property="username" />
        <result column="password" property="password" />
        <result column="email" property="email" />
        <result column="phone" property="phone" />
        <result column="avatar" property="avatar" />
        <result column="real_name" property="realName" />
        <result column="department" property="department" />
        <result column="position" property="position" />
        <result column="status" property="status" />
        <result column="last_login_time" property="lastLoginTime" />
        <result column="last_login_ip" property="lastLoginIp" />
        <result column="deleted" property="deleted" />
        <result column="create_time" property="createTime" />
        <result column="update_time" property="updateTime" />
        <result column="create_by" property="createBy" />
        <result column="update_by" property="updateBy" />
    </resultMap>
    <!-- 通用查询结果列 -->
    <sql id="Base_Column_List">
        id, username, password, email, phone, avatar, real_name, department, position, status,
        last_login_time, last_login_ip, deleted, create_time, update_time, create_by, update_by
    </sql>
    <!-- 根据用户名查询用户 -->
    <select id="selectByUsername" resultMap="BaseResultMap">
        SELECT
        <include refid="Base_Column_List" />
        FROM kb_user
        WHERE username = #{username}
        AND deleted = 0
        LIMIT 1
    </select>
    <!-- 根据邮箱查询用户 -->
    <select id="selectByEmail" resultMap="BaseResultMap">
        SELECT
        <include refid="Base_Column_List" />
        FROM kb_user
        WHERE email = #{email}
        AND deleted = 0
        LIMIT 1
    </select>
    <!-- 根据手机号查询用户 -->
    <select id="selectByPhone" resultMap="BaseResultMap">
        SELECT
        <include refid="Base_Column_List" />
        FROM kb_user
        WHERE phone = #{phone}
        AND deleted = 0
        LIMIT 1
    </select>
</mapper>

3.2.3 用户上下文工具类

UserContextUtil.java - ThreadLocal用户上下文:

文件位置:kb-common/src/main/java/com/knowledge/base/common/utils/UserContextUtil.java

public class UserContextUtil {

    private static final ThreadLocal<Long> USER_ID_HOLDER = new ThreadLocal<>();
    private static final ThreadLocal<String> USERNAME_HOLDER = new ThreadLocal<>();
    private static final ThreadLocal<String> TOKEN_HOLDER = new ThreadLocal<>();

    /**
     * 设置当前用户ID
     */
    public static void setUserId(Long userId) {
        USER_ID_HOLDER.set(userId);
    }

    /**
     * 获取当前用户ID
     */
    public static Long getUserId() {
        return USER_ID_HOLDER.get();
    }

    /**
     * 设置当前用户名
     */
    public static void setUsername(String username) {
        USERNAME_HOLDER.set(username);
    }

    /**
     * 获取当前用户名
     */
    public static String getUsername() {
        return USERNAME_HOLDER.get();
    }

    /**
     * 设置Token
     */
    public static void setToken(String token) {
        TOKEN_HOLDER.set(token);
    }

    /**
     * 获取Token
     */
    public static String getToken() {
        return TOKEN_HOLDER.get();
    }

    /**
     * 清除当前用户上下文
     */
    public static void clear() {
        USER_ID_HOLDER.remove();
        USERNAME_HOLDER.remove();
        TOKEN_HOLDER.remove();
    }

    /**
     * 检查用户是否已登录
     */
    public static boolean isLoggedIn() {
        return getUserId() != null;
    }
}

3.2.4 DTO和VO类

LoginDTO.java - 登录请求DTO:

文件位置:kb-user-auth/src/main/java/com/knowledge/base/userauth/dto/LoginDTO.java

@Data
@Schema(description = "用户登录请求参数")
public class LoginDTO implements Serializable {

    private static final long serialVersionUID = 1L;

    /**
     * 用户名
     */
    @Schema(description = "用户名", required = true, example = "admin")
    @NotBlank(message = "用户名不能为空")
    private String username;

    /**
     * 密码
     */
    @Schema(description = "密码", required = true, example = "123456")
    @NotBlank(message = "密码不能为空")
    private String password;

    /**
     * 验证码(可选)
     */
    @Schema(description = "验证码", example = "1234")
    private String captcha;

    /**
     * 验证码Key(可选)
     */
    @Schema(description = "验证码Key")
    private String captchaKey;
}

UserVO.java - 用户信息VO:

文件位置:kb-user-auth/src/main/java/com/knowledge/base/userauth/vo/UserVO.java

@Data
@Schema(description = "用户信息")
public class UserVO implements Serializable {

    private static final long serialVersionUID = 1L;

    @Schema(description = "用户ID")
    private Long id;

    @Schema(description = "用户名")
    private String username;

    @Schema(description = "邮箱")
    private String email;

    @Schema(description = "手机号")
    private String phone;

    @Schema(description = "头像")
    private String avatar;

    @Schema(description = "真实姓名")
    private String realName;

    @Schema(description = "部门")
    private String department;

    @Schema(description = "岗位")
    private String position;

    @Schema(description = "状态")
    private Integer status;
}

UserDTO.java - 用户信息DTO:

文件位置:kb-user-auth/src/main/java/com/knowledge/base/userauth/dto/UserDTO.java

@Data
@Schema(description = "用户信息请求参数")
public class UserDTO implements Serializable {

    private static final long serialVersionUID = 1L;

    @Schema(description = "用户ID")
    private Long id;

    @Schema(description = "用户名", required = true)
    @NotBlank(message = "用户名不能为空")
    @Size(min = 4, max = 20, message = "用户名长度必须在4-20个字符之间")
    private String username;

    @Schema(description = "密码")
    @Size(min = 6, max = 20, message = "密码长度必须在6-20个字符之间")
    private String password;

    @Schema(description = "昵称")
    @Size(max = 50, message = "昵称长度不能超过50个字符")
    private String nickname;

    @Schema(description = "邮箱")
    @Email(message = "邮箱格式不正确")
    private String email;

    @Schema(description = "手机号")
    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
    private String phone;

    @Schema(description = "头像URL")
    private String avatar;

    @Schema(description = "状态(0-禁用,1-启用)")
    private Integer status;
}

3.2.5 公共基础类

ResultCode.java - 响应码枚举:

文件位置:kb-common/src/main/java/com/knowledge/base/common/result/ResultCode.java

@Getter
@AllArgsConstructor
public enum ResultCode {

    /**
     * 成功
     */
    SUCCESS(200, "操作成功"),

    /**
     * 失败
     */
    ERROR(500, "操作失败"),

    /**
     * 未授权
     */
    UNAUTHORIZED(401, "未授权,请先登录"),

    /**
     * 禁止访问
     */
    FORBIDDEN(403, "禁止访问"),

    /**
     * 用户名或密码错误
     */
    USERNAME_OR_PASSWORD_ERROR(10001, "用户名或密码错误"),

    /**
     * 用户不存在
     */
    USER_NOT_EXIST(10002, "用户不存在"),

    /**
     * 用户已存在
     */
    USER_ALREADY_EXIST(10003, "用户已存在"),

    /**
     * 用户已被禁用
     */
    USER_DISABLED(10004, "用户已被禁用");

    /**
     * 响应码
     */
    private final Integer code;

    /**
     * 响应消息
     */
    private final String message;
}

Result.java - 统一响应结果封装:

文件位置:kb-common/src/main/java/com/knowledge/base/common/result/Result.java

@Data
@JsonInclude(JsonInclude.Include.NON_NULL)
public class Result<T> implements Serializable {

    private static final long serialVersionUID = 1L;

    /**
     * 响应码
     */
    private Integer code;

    /**
     * 响应消息
     */
    private String message;

    /**
     * 响应数据
     */
    private T data;

    /**
     * 时间戳
     */
    private Long timestamp;

    /**
     * 成功返回(有数据)
     */
    public static <T> Result<T> success(T data) {
        return new Result<>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), data);
    }

    /**
     * 成功返回(自定义消息和数据)
     */
    public static <T> Result<T> success(String message, T data) {
        return new Result<>(ResultCode.SUCCESS.getCode(), message, data);
    }

    /**
     * 失败返回(自定义消息)
     */
    public static <T> Result<T> error(String message) {
        return new Result<>(ResultCode.ERROR.getCode(), message, null);
    }

    /**
     * 失败返回(使用结果码枚举)
     */
    public static <T> Result<T> error(ResultCode resultCode) {
        return new Result<>(resultCode.getCode(), resultCode.getMessage(), null);
    }

    private Result(Integer code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
        this.timestamp = System.currentTimeMillis();
    }
}

BusinessException.java - 业务异常类:

文件位置:kb-common/src/main/java/com/knowledge/base/common/exception/BusinessException.java

@Data
@EqualsAndHashCode(callSuper = true)
public class BusinessException extends RuntimeException {

    private Integer code;

    private String message;

    public BusinessException(String message) {
        super(message);
        this.code = ResultCode.ERROR.getCode();
        this.message = message;
    }

    public BusinessException(ResultCode resultCode) {
        super(resultCode.getMessage());
        this.code = resultCode.getCode();
        this.message = resultCode.getMessage();
    }

    public BusinessException(Integer code, String message) {
        super(message);
        this.code = code;
        this.message = message;
    }
}

MybatisPlusConfig.java - MyBatis Plus配置:

文件位置:kb-common/src/main/java/com/knowledge/base/common/config/MybatisPlusConfig.java

@Configuration
public class MybatisPlusConfig {

    /**
     * 配置MyBatis Plus拦截器
     *
     * <p>功能说明:</p>
     * <ul>
     *   <li>乐观锁插件:自动处理version字段的并发控制</li>
     *   <li>分页插件:自动处理分页查询</li>
     * </ul>
     */
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();

        // 添加乐观锁插件(必须在分页插件之前)
        interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());

        // 添加分页插件
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));

        return interceptor;
    }
}

GlobalExceptionHandler.java - 全局异常处理器:

文件位置:kb-common/src/main/java/com/knowledge/base/common/exception/GlobalExceptionHandler.java

@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    /**
     * 业务异常处理
     */
    @ExceptionHandler(BusinessException.class)
    public Result<Void> handleBusinessException(BusinessException e, HttpServletRequest request) {
        log.error("业务异常:URI={}, message={}", request.getRequestURI(), e.getMessage());
        return Result.error(e.getCode(), e.getMessage());
    }

    /**
     * 参数校验异常处理
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Void> handleValidationException(MethodArgumentNotValidException e, HttpServletRequest request) {
        log.error("参数校验异常:URI={}", request.getRequestURI());

        String message = e.getBindingResult().getFieldErrors().stream()
                .map(FieldError::getDefaultMessage)
                .collect(Collectors.joining(", "));

        return Result.error(ResultCode.PARAM_ERROR.getCode(), message);
    }

    /**
     * 认证异常处理
     */
    @ExceptionHandler(AccessDeniedException.class)
    public Result<Void> handleAccessDeniedException(AccessDeniedException e, HttpServletRequest request) {
        log.error("认证异常:URI={}, message={}", request.getRequestURI(), e.getMessage());
        return Result.error(ResultCode.FORBIDDEN);
    }

    /**
     * 系统异常处理
     */
    @ExceptionHandler(Exception.class)
    public Result<Void> handleException(Exception e, HttpServletRequest request) {
        log.error("系统异常:URI={}", request.getRequestURI(), e);
        return Result.error(ResultCode.INTERNAL_SERVER_ERROR);
    }
}

MyMetaObjectHandler.java - MyBatis Plus自动填充配置:

文件位置:kb-common/src/main/java/com/knowledge/base/common/handler/MyMetaObjectHandler.java

@Component
public class MyMetaObjectHandler implements MetaObjectHandler {

    /**
     * 插入时自动填充
     */
    @Override
    public void insertFill(MetaObject metaObject) {
        this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now());
        this.strictInsertFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
        this.strictInsertFill(metaObject, "deleted", Integer.class, 0);

        // 从UserContextUtil获取当前用户ID
        Long userId = UserContextUtil.getUserId();
        if (userId != null) {
            this.strictInsertFill(metaObject, "createBy", Long.class, userId);
            this.strictInsertFill(metaObject, "updateBy", Long.class, userId);
        }
    }

    /**
     * 更新时自动填充
     */
    @Override
    public void updateFill(MetaObject metaObject) {
        this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());

        // 从UserContextUtil获取当前用户ID
        Long userId = UserContextUtil.getUserId();
        if (userId != null) {
            this.strictUpdateFill(metaObject, "updateBy", Long.class, userId);
        }
    }
}

3.2.6 Service接口

UserService.java - 用户Service接口:

文件位置:kb-user-auth/src/main/java/com/knowledge/base/userauth/service/UserService.java

public interface UserService extends IService<User> {

    /**
     * 用户登录
     *
     * @param username 用户名
     * @param password 密码
     * @return 登录响应信息
     */
    LoginVO login(String username, String password);

    /**
     * 用户退出
     *
     * @param token 令牌
     */
    void logout(String token);

    /**
     * 根据用户名查询用户
     *
     * @param username 用户名
     * @return 用户信息
     */
    User getByUsername(String username);

    /**
     * 获取当前登录用户信息
     *
     * @return 用户信息
     */
    UserVO getCurrentUserInfo();
}

3.3 登录接口实现

UserService.login()方法:

文件位置:kb-user-auth/src/main/java/com/knowledge/base/userauth/service/impl/UserServiceImpl.java

@Override
public LoginVO login(String username, String password) {
    log.info("用户登录:username={}", username);

    // 1. 查询用户
    User user = getByUsername(username);
    if (user == null) {
        throw new BusinessException(ResultCode.USER_NOT_EXIST);
    }

    // 2. 检查用户状态
    if (user.getStatus() == 0) {
        throw new BusinessException(ResultCode.USER_DISABLED);
    }

    // 3. 验证密码(使用BCrypt)
    if (!BCrypt.checkpw(password, user.getPassword())) {
        throw new BusinessException(ResultCode.USERNAME_OR_PASSWORD_ERROR);
    }

    // 4. 生成JWT Token
    String accessToken = jwtTokenUtil.generateAccessToken(user.getId());
    String refreshToken = jwtTokenUtil.generateRefreshToken(user.getId());

    // 5. 构建用户信息
    LoginVO.UserInfo userInfo = LoginVO.UserInfo.builder()
        .userId(user.getId())
        .username(user.getUsername())
        .nickname(user.getRealName())
        .email(user.getEmail())
        .phone(user.getPhone())
        .avatar(user.getAvatar())
        .build();

    // 6. 构建登录响应
    return LoginVO.builder()
        .accessToken(accessToken)
        .refreshToken(refreshToken)
        .tokenType("Bearer")
        .expiresIn(7200L)
        .userInfo(userInfo)
        .build();
}

LoginVO.java - 登录响应VO:

文件位置:kb-user-auth/src/main/java/com/knowledge/base/userauth/vo/LoginVO.java

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "用户登录响应信息")
public class LoginVO implements Serializable {

    private static final long serialVersionUID = 1L;

    /**
     * 访问令牌
     */
    @Schema(description = "访问令牌")
    private String accessToken;

    /**
     * 刷新令牌
     */
    @Schema(description = "刷新令牌")
    private String refreshToken;

    /**
     * 令牌类型
     */
    @Schema(description = "令牌类型")
    private String tokenType;

    /**
     * 过期时间(秒)
     */
    @Schema(description = "过期时间(秒)")
    private Long expiresIn;

    /**
     * 用户信息
     */
    @Schema(description = "用户信息")
    private UserInfo userInfo;

    /**
     * 用户信息内部类
     */
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @Schema(description = "用户信息")
    public static class UserInfo implements Serializable {

        private static final long serialVersionUID = 1L;

        /**
         * 用户ID
         */
        @Schema(description = "用户ID")
        private Long userId;

        /**
         * 用户名
         */
        @Schema(description = "用户名")
        private String username;

        /**
         * 昵称
         */
        @Schema(description = "昵称")
        private String nickname;

        /**
         * 邮箱
         */
        @Schema(description = "邮箱")
        private String email;

        /**
         * 手机号
         */
        @Schema(description = "手机号")
        private String phone;

        /**
         * 头像URL
         */
        @Schema(description = "头像URL")
        private String avatar;
    }
}

关键步骤说明:

  1. 用户查询:通过用户名查询数据库
  2. 状态检查:禁用用户不允许登录
  3. 密码验证:使用BCrypt.checkpw验证加密后的密码
  4. Token生成:调用JWT工具类生成访问令牌和刷新令牌
  5. 响应构建:构建统一的登录响应VO

关键步骤说明:

  1. 参数校验:确保用户名和密码不为空
  2. 用户查询:通过用户名查询数据库,同时检查逻辑删除标记
  3. 密码验证:使用BCryptPasswordEncoder验证加密后的密码
  4. 状态检查:禁用用户不允许登录
  5. Token生成:调用JWT工具类生成访问令牌和刷新令牌
  6. 登录记录:更新最后登录时间和IP地址

3.4 JWT认证过滤器

JwtAuthenticationFilter.java - 核心功能:从请求头提取Token、验证、设置安全上下文:

文件位置:kb-user-auth/src/main/java/com/knowledge/base/userauth/filter/JwtAuthenticationFilter.java

@Slf4j
@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    @Resource
    private JwtTokenUtil jwtTokenUtil;

    @Resource
    private UserMapper userMapper;

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

        String requestUri = request.getRequestURI();
        String method = request.getMethod();

        log.info("========== JwtAuthenticationFilter 开始 ==========");
        log.info("请求URI: {}, Method: {}", requestUri, method);

        // 1. 从请求中提取token
        String token = extractTokenFromRequest(request);
        log.info("提取的Token: {}", token != null ? token.substring(0, Math.min(30, token.length())) + "..." : "null");

        if (token != null) {
            try {
                // 2. 解析token获取用户信息
                UserInfo userInfo = parseToken(token);
                if (userInfo != null) {
                    log.info("Token解析成功: userId={}, username={}", userInfo.getUserId(), userInfo.getUsername());

                    // 3. 设置Spring Security认证上下文
                    setSecurityContext(userInfo, token, request);

                    // 4. 设置自定义ThreadLocal上下文
                    UserContextUtil.setUserId(userInfo.getUserId());
                    UserContextUtil.setUsername(userInfo.getUsername());
                    UserContextUtil.setToken(token);

                    log.info("JWT认证成功,已设置SecurityContext");
                } else {
                    log.warn("JWT Token无效或已过期: uri={}, method={}", requestUri, method);
                }
            } catch (Exception e) {
                log.error("JWT认证异常: uri={}, method={}, error={}", requestUri, method, e.getMessage(), e);
                // 认证失败不阻断请求,由业务层判断是否需要认证
            }
        } else {
            log.warn("请求未携带Token: uri={}, method={}", requestUri, method);
        }

        try {
            log.info("执行后续过滤器链...");
            // 5. 执行后续过滤器
            filterChain.doFilter(request, response);
            log.info("后续过滤器链执行完毕,响应状态: {}", response.getStatus());
        } finally {
            // 6. 请求结束后清理上下文,防止ThreadLocal内存泄漏
            UserContextUtil.clear();
            log.info("========== JwtAuthenticationFilter 结束 ==========");
        }
    }

    /**
     * 设置Spring Security认证上下文
     *
     * <p>这是解决403错误的关键步骤</p>
     * <p>Spring Security通过SecurityContextHolder判断用户是否已认证</p>
     */
    private void setSecurityContext(UserInfo userInfo, String token, HttpServletRequest request) {
        log.info("开始设置SecurityContext...");

        List<SimpleGrantedAuthority> authorities = getUserAuthorities(userInfo);
        log.info("用户权限列表: {}", authorities);

        // 创建认证对象
        // 使用三个参数的构造函数:principal, credentials, authorities
        // 这样创建的对象会自动标记为已认证(authenticated=true)
        UsernamePasswordAuthenticationToken authentication =
                new UsernamePasswordAuthenticationToken(
                        userInfo.getUserId(),  // principal:用户ID
                        token,                // credentials:保留token用于追踪
                        authorities          // authorities:权限列表
                );

        log.info("创建认证对象: principal={}, credentials长度={}, authorities={}",
                userInfo.getUserId(), token.length(), authorities);

        // 设置认证详情
        WebAuthenticationDetails details = new WebAuthenticationDetailsSource().buildDetails(request);
        authentication.setDetails(details);
        log.info("设置认证详情: remoteAddress={}, sessionId={}",
                details.getRemoteAddress(), details.getSessionId());

        // 将认证对象设置到Spring Security上下文中
        SecurityContextHolder.getContext().setAuthentication(authentication);
        log.info("已将认证对象设置到SecurityContextHolder");

        // 验证设置是否成功
        var auth = SecurityContextHolder.getContext().getAuthentication();
        log.info("验证SecurityContext: is null={}, isAuthenticated={}, principal={}, authorities={}, class={}",
                auth == null,
                auth != null && auth.isAuthenticated(),
                auth != null ? auth.getPrincipal() : null,
                auth != null ? auth.getAuthorities() : null,
                auth != null ? auth.getClass().getSimpleName() : null);
    }

    /**
     * 获取用户权限列表
     *
     * <p>TODO: 后续可以从数据库加载用户的实际权限</p>
     */
    private List<SimpleGrantedAuthority> getUserAuthorities(UserInfo userInfo) {
        List<SimpleGrantedAuthority> authorities = new ArrayList<>();

        // 默认添加普通用户权限
        authorities.add(new SimpleGrantedAuthority("ROLE_USER"));

        // TODO: 从数据库加载用户的角色和权限
        // authorities.add(new SimpleGrantedAuthority("ROLE_ADMIN"));

        return authorities;
    }

    /**
     * 解析Token获取用户信息
     *
     * <p>支持两种Token格式:</p>
     * <ol>
     *   <li>真实JWT Token:使用JwtTokenUtil解析</li>
     *   <li>Mock Token:开发测试使用,格式为 mock-access-token-{userId}</li>
     * </ol>
     */
    private UserInfo parseToken(String token) {
        // 优先尝试解析真实的JWT Token
        if (jwtTokenUtil.validateToken(token)) {
            Long userId = jwtTokenUtil.getUserIdFromToken(token);
            if (userId != null) {
                return loadUserInfo(userId);
            }
        }

        // 开发环境:支持Mock Token
        if (token.startsWith("mock-access-token-")) {
            return parseMockToken(token);
        }

        return null;
    }

    /**
     * 加载用户信息
     *
     * <p>从数据库查询用户详细信息,避免每次请求都查询数据库</p>
     * <p>后续可优化为缓存实现</p>
     */
    private UserInfo loadUserInfo(Long userId) {
        try {
            User user = userMapper.selectById(userId);
            if (user != null && user.getStatus() == 1) {
                return UserInfo.builder()
                        .userId(user.getId())
                        .username(user.getUsername())
                        .build();
            }
        } catch (Exception e) {
            log.error("查询用户信息失败: userId={}", userId, e);
        }
        return null;
    }

    /**
     * 解析Mock Token(开发测试用)
     */
    private UserInfo parseMockToken(String token) {
        try {
            String userIdStr = token.substring("mock-access-token-".length());
            Long userId = Long.parseLong(userIdStr);
            return loadUserInfo(userId);
        } catch (NumberFormatException e) {
            log.error("解析Mock Token失败: {}", e.getMessage());
        }
        return null;
    }

    /**
     * 从请求头中提取Token
     *
     * <p>支持两种格式:</p>
     * <ol>
     *   <li>Authorization: Bearer {token}</li>
     *   <li>Authorization: {token}</li>
     * </ol>
     */
    private String extractTokenFromRequest(HttpServletRequest request) {
        String bearerToken = request.getHeader("Authorization");
        if (bearerToken != null && bearerToken.startsWith("Bearer ")) {
            return bearerToken.substring(7);
        }
        return bearerToken;
    }

    /**
     * 判断是否需要跳过此过滤器
     *
     * <p>以下路径不需要JWT认证:</p>
     * <ul>
     *   <li>登录、注册等公开接口</li>
     *   <li>健康检查、监控等管理接口</li>
     *   <li>API文档接口</li>
     *   <li>OPTIONS预检请求</li>
     * </ul>
     */
    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        String path = request.getRequestURI();

        return path.startsWith("/auth/login") ||
                path.startsWith("/auth/register") ||
                path.startsWith("/public/") ||
                path.startsWith("/actuator/") ||
                path.startsWith("/doc.html") ||
                path.startsWith("/swagger-resources/") ||
                path.startsWith("/v3/api-docs/") ||
                path.startsWith("/webjars/") ||
                "OPTIONS".equals(request.getMethod());
    }

    /**
     * 用户信息内部类
     */
    @lombok.Data
    @lombok.Builder
    private static class UserInfo {
        private Long userId;
        private String username;
    }
}

过滤器执行顺序:

请求 → CorsFilter → JwtAuthenticationFilter →
       UsernamePasswordAuthenticationFilter → ExceptionTranslationFilter →
       FilterSecurityInterceptor → Controller

关键点说明:

  1. Token提取:从Authorization header提取Bearer Token
  2. Token验证:使用JwtTokenUtil验证Token有效性
  3. 用户加载:从数据库加载完整用户信息
  4. 上下文设置:设置Spring Security的SecurityContext和自定义ThreadLocal
  5. 异常处理:认证失败不阻断请求,由业务层判断
  6. 资源清理:finally块清理ThreadLocal,防止内存泄漏
  7. 路径过滤:shouldNotFilter配置公开接口列表

3.5 Spring Security配置

SecurityConfig.java - 配置无状态会话和JWT过滤器:

文件位置:kb-user-auth/src/main/java/com/knowledge/base/userauth/config/SecurityConfig.java

@Slf4j
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {

    @Resource
    private JwtAuthenticationFilter jwtAuthenticationFilter;

    /**
     * 配置安全过滤链
     */
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        log.info("==================== 配置Spring Security ====================");

        http
                // 禁用CSRF保护(使用JWT不需要CSRF)
                .csrf(AbstractHttpConfigurer::disable)

                // 配置无状态会话管理(不使用Session)
                .sessionManagement(session -> session
                        .sessionCreationPolicy(SessionCreationPolicy.STATELESS))

                // 禁用CORS(由网关统一处理)
                .cors(AbstractHttpConfigurer::disable)

                // 添加JWT认证过滤器(在用户名密码认证过滤器之前)
                .addFilterBefore(jwtAuthenticationFilter,
                        org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter.class)

                // 配置授权规则
                .authorizeHttpRequests(auth -> auth
                        // 登录和注册接口:完全开放
                        .requestMatchers("/auth/login", "/auth/register", "/auth/auth/**").permitAll()

                        // /me接口:需要认证(但不需要特定角色)
                        .requestMatchers("/auth/me").authenticated()

                        // 测试端点:用于诊断403问题
                        .requestMatchers("/auth/debug/**", "/auth/test/**").permitAll()

                        // 公开API:完全开放
                        .requestMatchers("/public/**").permitAll()

                        // WebSocket:完全开放
                        .requestMatchers("/ws/**").permitAll()

                        // 健康检查和监控:完全开放
                        .requestMatchers("/actuator/**").permitAll()

                        // API文档:完全开放(开发环境)
                        .requestMatchers("/doc.html", "/swagger-resources/**",
                                "/v3/api-docs/**", "/webjars/**").permitAll()

                        // 测试端点:完全开放
                        .requestMatchers("/test", "/test-error").permitAll()

                        // OPTIONS预检请求:完全开放(支持CORS)
                        .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()

                        // 其他所有请求:需要认证
                        .anyRequest().authenticated()
                );

        log.info("Spring Security配置完成:JWT认证模式,无状态会话");
        log.info("==================== Spring Security 配置完毕 ====================");
        return http.build();
    }

    /**
     * 配置密码编码器
     *
     * <p>使用BCrypt算法,强度为10</p>
     * <p>BCrypt特点:</p>
     * <ul>
     *   <li>自动加盐:每次加密结果都不同</li>
     *   <li>强度可调:默认10,范围4-31</li>
     *   <li>单向加密:不可逆向解密</li>
     * </ul>
     */
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(10);
    }
}

配置说明:

  • SessionCreationPolicy.STATELESS:不使用HttpSession,完全依赖JWT Token
  • JwtAuthenticationFilter位置:在UsernamePasswordAuthenticationFilter之前执行
  • PasswordEncoder:使用BCrypt加密密码,强度为10
  • 公开接口:登录、注册、测试、文档等接口无需认证
  • 受保护接口:其他所有接口需要认证
  • OPTIONS请求:完全开放,支持CORS预检

四、接口定义

4.1 登录接口

请求:

POST /api/auth/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "123456"
}

响应(成功):

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
    "tokenType": "Bearer",
    "expiresIn": 7200,
    "userInfo": {
      "id": "1000000000000000001",
      "username": "admin",
      "email": "admin@example.com",
      "avatar": "https://example.com/avatar.jpg"
    }
  }
}

响应(失败):

{
  "code": 500,
  "message": "用户名或密码错误",
  "data": null
}

4.2 获取当前用户信息接口

请求:

GET /api/auth/auth/me
Authorization: Bearer {accessToken}

响应(成功):

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": "1000000000000000001",
    "username": "admin",
    "email": "admin@example.com",
    "realName": "系统管理员",
    "department": "技术部",
    "position": "系统架构师",
    "avatar": "https://example.com/avatar.jpg"
  }
}

响应(未认证):

{
  "code": 403,
  "message": "未认证或Token已过期",
  "data": null
}

4.3 Controller实现

AuthController.java - 认证接口Controller:

文件位置:kb-user-auth/src/main/java/com/knowledge/base/userauth/controller/AuthController.java

@Slf4j
@RestController
@RequestMapping("/auth")
@Tag(name = "认证管理", description = "用户认证相关接口")
public class AuthController {

    @Resource
    private UserService userService;

    /**
     * 获取当前登录用户信息
     *
     * @param request HTTP请求
     * @return 当前用户信息
     */
    @GetMapping("/me")
    @Operation(summary = "获取当前用户信息", description = "获取当前登录用户的详细信息")
    public Result<UserVO> getCurrentUser(HttpServletRequest request) {
        log.info("==================== /me 接口被调用 ====================");
        log.info("请求URI: {}", request.getRequestURI());
        log.info("请求Method: {}", request.getMethod());
        log.info("Authorization Header: {}", request.getHeader("Authorization"));

        // 检查Spring Security的认证状态
        var authentication = org.springframework.security.core.context.SecurityContextHolder.getContext().getAuthentication();
        log.info("Spring Security认证状态:");
        log.info("  - Authentication: {}", authentication);
        log.info("  - isAuthenticated: {}", authentication != null && authentication.isAuthenticated());

        // 检查UserContextUtil的状态
        log.info("UserContextUtil状态:");
        log.info("  - UserId: {}", com.knowledge.base.common.utils.UserContextUtil.getUserId());
        log.info("  - Username: {}", com.knowledge.base.common.utils.UserContextUtil.getUsername());

        try {
            UserVO userVO = userService.getCurrentUserInfo();
            log.info("获取用户信息成功: {}", userVO);
            return Result.success(userVO);
        } catch (Exception e) {
            log.error("获取用户信息失败", e);
            throw e;
        }
    }

    /**
     * 用户登录
     *
     * @param loginDTO 登录请求参数
     * @return 登录响应信息
     */
    @PostMapping("/login")
    @Operation(summary = "用户登录", description = "用户使用用户名密码登录系统")
    public Result<LoginVO> login(@Valid @RequestBody LoginDTO loginDTO) {
        log.info("用户登录请求:username={}", loginDTO.getUsername());

        LoginVO loginVO = userService.login(loginDTO.getUsername(), loginDTO.getPassword());
        return Result.success(loginVO);
    }

    /**
     * 用户退出
     *
     * @param token 访问令牌
     * @return 响应结果
     */
    @PostMapping("/logout")
    @Operation(summary = "用户退出", description = "用户退出登录")
    public Result<Void> logout(@RequestHeader("Authorization") String token) {
        log.info("用户退出登录");

        userService.logout(token);
        return Result.success();
    }

    /**
     * 刷新Token
     *
     * @param refreshToken 刷新令牌
     * @return 新的访问令牌
     */
    @PostMapping("/refresh")
    @Operation(summary = "刷新Token", description = "使用刷新令牌获取新的访问令牌")
    public Result<LoginVO> refresh(@RequestParam String refreshToken) {
        log.info("刷新Token");

        // TODO: 实现刷新Token逻辑
        return Result.success();
    }

    /**
     * 测试端点 - 用于验证响应体是否能正常返回
     *
     * @return 测试响应
     */
    @GetMapping("/test")
    @Operation(summary = "测试端点", description = "测试响应体返回")
    public Result<String> test() {
        log.info("测试端点被调用");
        return Result.success("测试响应成功", "这是测试数据");
    }

    /**
     * 测试异常端点 - 用于验证异常响应是否能正常返回
     *
     * @return 测试异常响应
     */
    @GetMapping("/test-error")
    @Operation(summary = "测试异常端点", description = "测试异常响应")
    public Result<String> testError() {
        log.info("测试异常端点被调用");
        throw new com.knowledge.base.common.exception.BusinessException("这是一个测试异常");
    }
}

Controller关键点说明:

  1. @RestController:标记为REST控制器,返回JSON格式数据
  2. @RequestMapping("/auth"):定义控制器基础路径
  3. @Tag:Swagger文档注解,用于API文档生成
  4. @Resource:依赖注入,注入UserService
  5. 日志记录:记录关键操作信息,便于问题排查
  6. 异常处理:使用try-catch捕获异常,由全局异常处理器统一处理
  7. TODO标记:标识需要后续实现的功能(如Token刷新)

最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏