开发喵星球

Sa-Token 是一个轻量级、灵活且功能丰富的 Java 权限认证框架，专为前后端分离架构设计。它支持登录认证、权限认证、单点登录、OAuth2、微服务网关鉴权等多种权限管理需求，提供了一种简单而强大的 API。本文将逐步介绍如何在若依（RuoYi）框架中集成 Sa-Token，实现 APP 或小程序用户的权限认证和管理。

1、Sa-Token 介绍

Sa-Token 以“极简 API”著称，开发者仅需几行代码即可实现用户认证、权限验证等操作。尤其对于 APP 和小程序等应用场景，Sa-Token 能帮助我们快速集成登录认证功能，让权限控制变得高效便捷。

接下来，我们将逐步配置和实现若依框架中的 Sa-Token 集成。

2、集成步骤

1. 引入 Sa-Token 依赖

首先，在项目的 ruoyi-common 模块的 pom.xml 文件中添加 Sa-Token 相关的依赖。

<!-- Sa-Token 基础依赖 -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot-starter</artifactId>
    <version>1.30.0</version>
</dependency>

<!-- Sa-Token Redis 扩展，确保会话数据的持久化存储 -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-dao-redis-jackson</artifactId>
    <version>1.30.0</version>
</dependency>

注意：如果使用的是 Spring Boot 3.x，请将 sa-token-spring-boot-starter 修改为 sa-token-spring-boot3-starter。

2. 配置拦截器

为确保对 APP 和小程序接口请求的权限控制，需在拦截器中配置放行策略，允许未授权的用户访问指定路径。

在 ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java 中修改拦截器配置：

// 开放 APP 和小程序的公共接口
.antMatchers("/api/**").permitAll()

此配置允许未登录用户访问 /api/** 路径下的接口，适用于 APP 和小程序的认证路径。

3. 创建 Sa-Token 配置类

接下来，创建 Sa-Token 的配置类，用于注册路由拦截器并对 APP 或小程序的请求进行统一拦截。

在 ruoyi-framework/src/main/java/com/ruoyi/framework/config/ 路径下新建 SaTokenConfig.java 文件，内容如下：

package com.ruoyi.framework.config;

import cn.dev33.satoken.interceptor.SaRouteInterceptor;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class SaTokenConfig implements WebMvcConfigurer {

    // 注册 Sa-Token 路由拦截器
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new SaRouteInterceptor())
                .addPathPatterns("/api/**") // 拦截所有 APP 或小程序请求
                .excludePathPatterns("/api/auth/**"); // 排除登录相关请求
    }
}

此配置将所有 /api/** 路径请求纳入 Sa-Token 的权限管理中，但排除登录路径（如 /api/auth/**），以便未登录用户可以正常访问认证接口。

4. 实现登录接口

为 APP 和小程序用户创建登录接口，实现账号密码认证，并返回 Token。

在 ruoyi-admin/src/main/java/com/ruoyi/web/api/ 路径下创建 AuthApi.java：

package com.ruoyi.web.api;

import cn.dev33.satoken.stp.StpUtil;
import com.ruoyi.common.core.domain.AjaxResult;
import com.ruoyi.common.core.domain.entity.SysUser;
import com.ruoyi.common.core.domain.model.LoginBody;
import com.ruoyi.common.utils.SecurityUtils;
import com.ruoyi.system.service.ISysUserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

/**
 * APP授权认证API
 */
@RestController
@RequestMapping("/api/auth")
@Api("APP授权认证API")
public class AuthApi {

    @Autowired
    private ISysUserService userService;

    @PostMapping("/login")
    @ApiOperation("账号密码登录")
    public AjaxResult login(@RequestBody LoginBody loginBody) {
        // 验证用户信息
        SysUser user = userService.selectUserByUserName(loginBody.getUsername());
        if (user == null || !SecurityUtils.matchesPassword(loginBody.getPassword(), user.getPassword())) {
            return AjaxResult.error("用户名或密码错误");
        }

        // 创建 Token
        StpUtil.login(user.getUserId());
        String tokenValue = StpUtil.getTokenValue();

        // 返回 Token 信息
        return AjaxResult.success()
                .put(StpUtil.getTokenName(), tokenValue)
                .put("userId", user.getUserId());
    }
}

此接口接收登录请求，验证用户信息，通过 Sa-Token 创建并返回 Token，供后续的用户会话管理使用。

5. 添加用户会话管理接口

为便于用户管理和退出登录，我们继续为 APP 或小程序的用户提供相关接口。

在 ruoyi-admin/src/main/java/com/ruoyi/web/api/ums/ 路径下创建 UmsUserApi.java：

package com.ruoyi.web.api.ums;

import cn.dev33.satoken.stp.StpUtil;
import com.ruoyi.common.core.domain.AjaxResult;
import com.ruoyi.common.core.domain.entity.SysUser;
import com.ruoyi.system.service.ISysUserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/user")
@Api("用户模块API")
public class UmsUserApi {

    @Autowired
    private ISysUserService userService;

    @GetMapping("/info")
    @ApiOperation("获取用户信息")
    public AjaxResult info() {
        // 获取当前用户信息
        long userId = StpUtil.getLoginIdAsLong();
        SysUser user = userService.selectUserById(userId);
        return AjaxResult.success(user);
    }

    @PostMapping("/logout")
    @ApiOperation("退出登录")
    public AjaxResult logout() {
        // 注销用户登录
        StpUtil.logout();
        return AjaxResult.success();
    }
}

此接口包含查询用户信息和注销登录的方法，方便 APP 用户进行会话管理。

6. 使用权限控制注解

在实际业务方法上，您可以通过 Sa-Token 提供的注解来进行权限控制，如使用 @SaCheckPermission("user:info") 来验证特定权限。

3、总结

通过上述步骤，我们成功在 RuoYi 框架中集成了 Sa-Token，轻松实现了 APP 和小程序用户的登录、会话管理及权限控制功能。这种配置模式使得 Sa-Token 成为管理系统中权限认证的利器。