Spring Boot + Sa-Token 权限认证项目小案例Spring Boot + Sa-Token 权限认证项

Spring Boot + Sa-Token 权限认证项目技术栈详解

本文详细记录了一个基于 Spring Boot 3 和 Sa-Token 的权限认证 demo 项目所使用的技术栈、框架和核心注解。

一、项目概述

本项目是一个基于 Spring Boot 3.4.3 和 Sa-Token 1.44.0 的轻量级权限认证演示项目，实现了用户登录、注销、Token 管理等核心功能，并配备了统一异常处理机制。

项目基本信息：

JDK 版本：Java 17
构建工具：Maven
应用名称：sa-token-demo-springboot
服务端口：8081

二、核心技术栈

2.1 Spring Boot 3.4.3

依赖坐标：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.4.3</version>
</dependency>

主要特性：

自动配置机制，简化项目搭建
内嵌 Tomcat 服务器，独立运行
约定优于配置的理念
完善的 starter 依赖管理

2.2 Spring Web MVC

依赖坐标：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

提供的能力：

RESTful API 开发支持
HTTP 请求处理和响应
JSON 数据序列化/反序列化
请求参数绑定和验证

2.3 Spring AOP

依赖坐标：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

应用场景：

切面编程支持
方法拦截和增强
日志记录
权限校验（与 Sa-Token 配合）

2.4 Sa-Token 1.44.0

依赖坐标：

<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot3-starter</artifactId>
    <version>1.44.0</version>
</dependency>

Sa-Token 核心功能：

✅ 登录认证
✅ Token 管理
✅ 会话管理
✅ 权限验证
✅ 角色验证
✅ 二级认证
✅ SSO 单点登录

本项目中的使用：

StpUtil.login() - 用户登录
StpUtil.isLogin() - 检查登录状态
StpUtil.getTokenInfo() - 获取 Token 信息
StpUtil.logout() - 用户注销
SaResult - 统一返回结果

2.5 Lombok

依赖坐标：

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.30</version>
    <scope>provided</scope>
</dependency>

作用：

简化 Java 代码编写
自动生成 Getter/Setter/toString 等方法
减少样板代码

三、核心注解详解

3.1 Spring Boot 核心注解

`@SpringBootApplication`

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

说明： 组合注解，包含：

@Configuration - 配置类
@EnableAutoConfiguration - 启用自动配置
@ComponentScan - 组件扫描

3.2 Spring MVC 注解

`@RestController`

@RestController
@RequestMapping("/user/")
public class UserController {
    // ...
}

说明：

@Controller + @ResponseBody 的组合
标识该类为 RESTful 控制器
所有方法返回值直接作为 HTTP 响应体

`@RequestMapping`

@RequestMapping("doLogin")
public SaResult doLogin(String name, String pwd) {
    // ...
}

说明： 映射 HTTP 请求到处理方法

可用在类级别（基础路径）
可用在方法级别（具体路径）
支持 GET、POST、PUT、DELETE 等

`@GetMapping`

@GetMapping("/{id}")
public String getUser(@PathVariable Long id) {
    // ...
}

说明：

@RequestMapping(method = RequestMethod.GET) 的简写
专门处理 GET 请求

`@PathVariable`

public String getUser(@PathVariable Long id) {
    // ...
}

说明： 绑定 URL 路径变量到方法参数

3.3 全局异常处理注解

`@RestControllerAdvice`

@RestControllerAdvice
public class GlobalExceptionHandler {
    // ...
}

说明：

@ControllerAdvice + @ResponseBody 的组合
全局异常处理器
适用于 RESTful API

`@ExceptionHandler`

@ExceptionHandler(UserNotFoundException.class)
public ResponseEntity<ErrorResponse> handleUserNotFoundException(
    UserNotFoundException ex, WebRequest request) {
    // ...
}

说明：

声明该方法处理特定类型的异常
可指定多个异常类型
优先级高于容器默认异常处理

3.4 Sa-Token 相关类

`StpUtil` - 登录工具类

// 登录
StpUtil.login(10001);

// 检查是否登录
StpUtil.isLogin();

// 获取 Token 信息
StpUtil.getTokenInfo();

// 注销
StpUtil.logout();

`SaResult` - 统一返回结果

// 成功响应
return SaResult.ok("登录成功");

// 失败响应
return SaResult.error("登录失败");

// 带数据的成功响应
return SaResult.data(StpUtil.getTokenInfo());

`SaManager` - Sa-Token 管理器

System.out.println("Sa-Token 配置如下：" + SaManager.getConfig());

四、配置文件详解

application.yaml

# 端口
server:
  port: 8081

spring:
  application:
    name: sa-token-demo

# sa-token 配置
sa-token:
  # token 名称 (同时也是 cookie 名称)
  token-name: sa-token-demo
  # token 有效期（单位：秒）默认 30 天，-1 代表永久有效
  timeout: 2592000
  # token 最低活跃频率（单位：秒）
  active-timeout: -1
  # 是否允许同一账号多地同时登录
  is-concurrent: true
  # 在多人登录同一账号时，是否共用一个 token
  is-share: false
  # token 风格
  token-style: uuid
  # 是否输出操作日志
  is-log: true

配置项说明：

token-name: Token 参数名称
timeout: Token 有效期（30 天 = 2592000 秒）
active-timeout: 最低活跃频率（-1 表示不限制）
is-concurrent: 是否允许多地登录
is-share: 是否共享 Token
token-style: Token 生成风格（uuid/simple-uuid/random-32 等）
is-log: 是否输出操作日志

五、项目架构设计

5.1 包结构

src/main/java/org/example/satokendemospringboot/
├── SaTokenDemoSpringbootApplication.java    # 启动类
├── controller/
│   └── UserController.java                  # 用户控制器
└── exception/
    ├── ErrorResponse.java                   # 错误响应体
    ├── GlobalExceptionHandler.java          # 全局异常处理器
    └── UserNotFoundException.java           # 自定义异常

5.2 统一错误响应体 - ErrorResponse

@Data
@NoArgsConstructor
@AllArgsConstructor
public class ErrorResponse {
    private Integer code;      // 错误码
    private String message;    // 错误消息
    private String detail;     // 错误详情
    private Long timestamp;    // 时间戳
    private String path;       // 请求路径
}

5.3 自定义异常 - UserNotFoundException

public class UserNotFoundException extends RuntimeException {
    public UserNotFoundException(String message) {
        super(message);
    }
}

5.4 全局异常处理器 - GlobalExceptionHandler

@RestControllerAdvice
public class GlobalExceptionHandler {
    private static final Logger logger = LoggerFactory.getLogger(
        GlobalExceptionHandler.class
    );

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleUserNotFoundException(
        UserNotFoundException ex, WebRequest request) {
        
        logger.error("UserNotFoundException: {}", ex.getMessage());
        
        ErrorResponse errorResponse = new ErrorResponse(
            404,
            ex.getMessage(),
            ex.toString(),
            System.currentTimeMillis(),
            request.getDescription(false).replace("uri=", "")
        );
        
        return new ResponseEntity<>(errorResponse, HttpStatus.NOT_FOUND);
    }
}

六、API 接口设计

6.1 用户登录

URL: POST /user/doLogin
参数: name, pwd
示例: http://localhost:8081/user/doLogin?name=zhang&pwd=123456

响应:

{
  "code": 200,
  "msg": "登录成功",
  "data": null
}

6.2 查询登录状态

URL: GET /user/isLogin
示例: http://localhost:8081/user/isLogin

响应:

{
  "code": 200,
  "msg": "是否登录：true",
  "data": null
}

6.3 查询 Token 信息

URL: GET /user/tokenInfo
示例: http://localhost:8081/user/tokenInfo
响应: 返回完整的 Token 信息（包括登录 ID、过期时间等）

6.4 用户注销

URL: POST /user/logout
示例: http://localhost:8081/user/logout

响应:

{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

6.5 测试异常处理

URL: GET /user/{id}
示例: http://localhost:8081/user/0

响应:

{
  "code": 404,
  "message": "用户不存在",
  "detail": "org.example.satokendemospringboot.exception.UserNotFoundException: 用户不存在",
  "timestamp": 1234567890,
  "path": "/user/0"
}

七、技术亮点总结

7.1 现代化技术选型

✅ Java 17: LTS 版本，性能优异
✅ Spring Boot 3.x: 最新稳定版本
✅ Sa-Token: 国产轻量级权限框架

7.2 优雅的代码设计

✅ Lombok: 减少样板代码
✅ 统一响应格式: SaResult + ErrorResponse
✅ 全局异常处理: @RestControllerAdvice

7.3 完善的认证机制

✅ Token 管理: 自动生成和管理
✅ 登录状态检测: 实时验证
✅ 灵活配置: YAML 外部化配置

7.4 开发体验优化

✅ 热部署: Spring DevTools（可选）
✅ 配置提示: spring-boot-configuration-processor
✅ 日志输出: Sa-Token 操作日志

八、扩展建议

8.1 可以添加的功能

Redis 集成: Token 存储到 Redis，支持分布式会话
数据库持久化: MySQL/PostgreSQL 存储用户数据
JWT 支持: 使用 JWT 作为 Token 载体
RBAC 权限: 角色和权限管理
接口限流: 防止恶意请求
操作日志: 记录用户操作行为

8.2 可以优化的方面

参数验证: 使用 Hibernate Validator
文档生成: Swagger/OpenAPI
单元测试: JUnit + Mockito
安全加固: HTTPS、CORS 配置
性能监控: Actuator + Prometheus

九、参考资源

官方文档

结语

本项目虽然是一个 demo，但涵盖了现代 Spring Boot 应用的核心要素：权限认证、统一响应、异常处理、配置管理。通过这些技术的组合使用，可以快速搭建一个生产级的后端应用框架。

希望这篇技术栈总结能帮助你更好地理解和扩展这个项目！🎉

作者: AI Assistant
创建时间: 2025-03-XX
最后更新: 2025-03-XX
标签: #SpringBoot #Sa-Token #Java #权限认证 #RESTful

Spring Boot + Sa-Token 权限认证项目小案例

Spring Boot + Sa-Token 权限认证项目技术栈详解

一、项目概述

二、核心技术栈

2.1 Spring Boot 3.4.3

2.2 Spring Web MVC

2.3 Spring AOP

2.4 Sa-Token 1.44.0

2.5 Lombok

三、核心注解详解

3.1 Spring Boot 核心注解

@SpringBootApplication

3.2 Spring MVC 注解

@RestController

@RequestMapping

@GetMapping

@PathVariable

3.3 全局异常处理注解

@RestControllerAdvice

@ExceptionHandler

3.4 Sa-Token 相关类

StpUtil - 登录工具类

SaResult - 统一返回结果

SaManager - Sa-Token 管理器

四、配置文件详解

application.yaml

五、项目架构设计

5.1 包结构

5.2 统一错误响应体 - ErrorResponse

5.3 自定义异常 - UserNotFoundException

5.4 全局异常处理器 - GlobalExceptionHandler

六、API 接口设计

6.1 用户登录

6.2 查询登录状态

6.3 查询 Token 信息

6.4 用户注销

6.5 测试异常处理

七、技术亮点总结

7.1 现代化技术选型

7.2 优雅的代码设计

7.3 完善的认证机制

7.4 开发体验优化

八、扩展建议

8.1 可以添加的功能

8.2 可以优化的方面

九、参考资源

官方文档

相关技术文章

结语

`@SpringBootApplication`

`@RestController`

`@RequestMapping`

`@GetMapping`

`@PathVariable`

`@RestControllerAdvice`

`@ExceptionHandler`

`StpUtil` - 登录工具类

`SaResult` - 统一返回结果

`SaManager` - Sa-Token 管理器