一、概述
用户认证服务(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.21.3 核心流程图
1.3.1 用户登录流程

1.3.2 Token认证流程

1.3.3 系统架构图


二、环境准备
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;
}
}关键步骤说明:
- 用户查询:通过用户名查询数据库
- 状态检查:禁用用户不允许登录
- 密码验证:使用BCrypt.checkpw验证加密后的密码
- Token生成:调用JWT工具类生成访问令牌和刷新令牌
- 响应构建:构建统一的登录响应VO
关键步骤说明:
- 参数校验:确保用户名和密码不为空
- 用户查询:通过用户名查询数据库,同时检查逻辑删除标记
- 密码验证:使用BCryptPasswordEncoder验证加密后的密码
- 状态检查:禁用用户不允许登录
- Token生成:调用JWT工具类生成访问令牌和刷新令牌
- 登录记录:更新最后登录时间和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关键点说明:
- Token提取:从Authorization header提取Bearer Token
- Token验证:使用JwtTokenUtil验证Token有效性
- 用户加载:从数据库加载完整用户信息
- 上下文设置:设置Spring Security的SecurityContext和自定义ThreadLocal
- 异常处理:认证失败不阻断请求,由业务层判断
- 资源清理:finally块清理ThreadLocal,防止内存泄漏
- 路径过滤: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关键点说明:
- @RestController:标记为REST控制器,返回JSON格式数据
- @RequestMapping("/auth"):定义控制器基础路径
- @Tag:Swagger文档注解,用于API文档生成
- @Resource:依赖注入,注入UserService
- 日志记录:记录关键操作信息,便于问题排查
- 异常处理:使用try-catch捕获异常,由全局异常处理器统一处理
- TODO标记:标识需要后续实现的功能(如Token刷新)