diff --git a/SaToken_Integration_Guide.md b/SaToken_Integration_Guide.md new file mode 100644 index 0000000..54351fa --- /dev/null +++ b/SaToken_Integration_Guide.md @@ -0,0 +1,212 @@ +# Spring Boot 集成 Sa-Token 实现 RBAC 权限管理（生产级实战） + +> 项目源码地址：[GitHub - xf-boot-base](https://github.com/XiongFengX/spring-boot-base-demo) +> 分支切换指令：`git checkout sa-token-rbac` (请替换为你实际的分支名) + +## 前言 + +随着项目从简单的 C 端应用扩展到 **B 端后台管理系统**，我们面临的核心痛点是如何高效实现 **RBAC（基于角色的访问控制）** 模型。 +简单的 Token 登录已无法满足需求，而手动从零开发一套包含角色管理、菜单权限、按钮拦截的权限系统，不仅耗时耗力，还容易引入安全漏洞。 + +**为了解决这一痛点，本文将引入 Sa-Token 框架。** +Sa-Token 是一个轻量级 Java 权限认证框架，它不仅能完美接管基础的登录认证，更能以极简的代码实现复杂的权限控制。**本文将带你一步步通过 Sa-Token，构建一套标准的、生产级的后台权限体系。** + +> **说明**：为了言简意赅，**文中只展示 Sa-Token 相关的核心功能代码**，不再罗列通用的基础设置（如全局异常处理、统一响应封装等）。无论您是从头新建项目，还是在已有架构上集成，这都是一份通用的标准参考方案。 + +--- + + + +## 二、准备环境 + +* **JDK**: 17+ +* **Spring Boot**: 3.3.3 +* **MySQL**: 8.0+ +* **Redis**: 5.0+ (生产环境下 Sa-Token 强依赖 Redis 做数据持久化) + +--- + +## 三、数据库设计 (RBAC 模型) + +为了实现标准的 RBAC 权限控制，我们设计了以下五张核心表。这套设计支撑了“用户 -> 角色 -> 权限”的经典模型。 + +### 1. 核心表结构说明 + +* **sys_user**: 用户表。存储用户的基本信息（账号、密码、昵称）。 +* **sys_role**: 角色表。定义系统中的角色（如：超级管理员、普通用户、运维人员）。 +* **sys_permission**: 权限（菜单）表。定义具体的资源权限标识（如 `user:add`, `user:delete`）。 +* **sys_user_role**: 用户-角色关联表。多对多关系，一个用户可以有多个角色。 +* **sys_role_permission**: 角色-权限关联表。多对多关系，一个角色可以拥有多个权限。 + +> **SQL 脚本**：项目完整源码中已包含 DDL 和初始化数据，请参考 `doc/sql` 目录。 + +--- + +## 四、Sa-Token 集成步骤 + +### 1. 引入依赖 + +除了核心 Starter，这里也引入了 Redis 集成插件。因为在生产环境（多实例部署）下，Session 通常需要是分布式的。 + +```xml + + + cn.dev33 + sa-token-spring-boot3-starter + 1.37.0 + + + + + cn.dev33 + sa-token-redis-jackson + 1.37.0 + + + + + org.apache.commons + commons-pool2 + +``` + +### 2. 配置文件 (application.yml) + +配置里有一个很有意思的决策点：`token-style`。 + +```yaml +sa-token: + token-name: Authorization + timeout: 2592000 # 30天 + activity-timeout: -1 + is-concurrent: true + is-read-header: true + token-style: uuid # 重点关注这里 +``` + +### 3. 聊聊关于 Token 风格的选择：JWT vs UUID + +在很多教程里，大家习惯把 Token 和 JWT 划等号，甚至觉得“不用 JWT 就是不现代”。但在 Sa-Token 的使用场景下，这里配置为 `uuid`。 + +**我们先看看 JWT 的本质**： +JWT (Json Web Token) 设计的初衷是**去中心化**。它把用户信息（User ID、角色等）签个名直接放在 Token 字符串里。 +* **优势**：服务端不需要查库，拿到 Token 解密就知道你是谁。特别适合微服务之间透传用户信息，或者超大规模（亿级用户）不想查 Redis 的场景。 +* **劣势**：**无法撤销**。一旦发出去， unless 你换秘钥，否则没法让它提前失效。这就导致了“踢人下线”、“封号”这种功能在纯 JWT 模式下很难做。 + +**现在的尴尬现状（Redis + JWT）**： +为了解决 JWT 不能踢人的问题，很多方案变成了：*“用 JWT 并在 Redis 里存一个黑名单/白名单”*。 +一旦引入了 Redis 查库，JWT **不查库** 的最大优势就没了。 +既然都要查 Redis，那我为什么还要传一个几百字节长的 JWT 字符串？还要浪费 CPU 去验签？ + +**为什么选择 UUID 模式？** +* **原理**：生成的 Token 就是一个简短的随机字符串。 +* **状态**：Redis 存 `Key: token`, `Value: UserInfo`。 +* **优势**：简单粗暴。想踢人？删 Redis Key 就行。Token 极短，省流量。 +* **适用性**：对于绝大多数企业级管理后台、App 后端，我们需要强管控能力（实时封号、踢人），UUID + Redis 是比较实用、高效的方案。 + +--- + +## 五、核心代码集成 + +### 1. 登录与注销 + +引入 Sa-Token 后，登录逻辑变得异常简单。框架会自动帮我们生成 Token、写入 Redis。 + +```java +// UserServiceImpl.java +public RetObj login(LoginInfoRes res) { + // ... 账号密码校验逻辑 ... + + // 登录，Sa-Token 会自动处理 Session 和 Token + StpUtil.login(user.getId()); + + // 我们还可以把当前用户信息缓存起来，方便后续随时取用 + StpUtil.getSession().set("loginUser", loginUser); + + // ... +} +``` + +### 2. 权限接口实现 (`StpInterface`) + +框架知道你登录了，但不知道你有什么权限。所以我们需要实现 `StpInterface` 接口，告诉 Sa-Token 如何去数据库查权限。 + +```java +@Component +public class StpInterfaceImpl implements StpInterface { + + @Autowired + private SysPermissionMapper sysPermissionMapper; + + @Override + public List getPermissionList(Object loginId, String loginType) { + // 返回该用户的所有权限标识，例如 ["user:add", "role:list"] + return sysPermissionMapper.getPermissionListByUserId(Long.valueOf(loginId.toString())); + } + + @Override + public List getRoleList(Object loginId, String loginType) { + // 返回该用户的所有角色标识，例如 ["admin"] + return sysRoleMapper.getRoleListByUserId(Long.valueOf(loginId.toString())); + } +} +``` + +--- + +## 六、拦截器设计的思考 + +在集成过程中，你可能会发现我的配置里注册了**两个**拦截器，这其实是为了兼容项目之前的一些老代码习惯。 + +```java +@Configuration +public class InterceptorConfig implements WebMvcConfigurer { + + @Autowired + private SaTokenContextInterceptor saTokenContextInterceptor; + + // 统一管理不需要拦截的路径（白名单） + private static final String[] EXCLUDE_PATHS = { "/user/login", "/doc.html", ... }; + + @Override + public void addInterceptors(InterceptorRegistry registry) { + // 1. Sa-Token 核心拦截器 (负责鉴权) + registry.addInterceptor(new SaInterceptor(handler -> { + StpUtil.checkLogin(); // 开启注解鉴权 + })).addPathPatterns("/**").excludePathPatterns(EXCLUDE_PATHS); + + // 2. 上下文注入拦截器 (负责数据搬运) + registry.addInterceptor(saTokenContextInterceptor) + .addPathPatterns("/**").excludePathPatterns(EXCLUDE_PATHS); + } +} +``` + +* **为什么要两个？** + `SaInterceptor` 负责“安检”，没登录直接拦回去。而 `SaTokenContextInterceptor` 是我自定义的，它负责在安检通过后，把 Sa-Token 里的用户信息拿出来放到 `ThreadLocal` 里，这样我原来的业务代码里 `SessionContext.get()` 依然能正常工作，不用大改业务逻辑。 +* **为什么要配置两遍路径？** + Spring MVC 的拦截器是独立的。如果不配置排除路径，第二个拦截器可能会尝试在未登录状态下去获取用户信息，虽然不一定会报错，但逻辑上不严谨。提取一个 `EXCLUDE_PATHS` 常量是比较优雅的解法。 + +--- + +## 七、使用效果 + +现在，Controller 层的权限控制变得非常干净： + +```java +// 必须具备 'super-admin' 角色 +@SaCheckRole("super-admin") +@PostMapping("/admin/config") + +// 必须具备 'user:add' 或 'user:update' 其中一个权限 +@SaCheckPermission(value = {"user:add", "user:update"}, mode = SaMode.OR) +@PostMapping("/user/edit") + +// 公开接口，忽略鉴权 +@SaIgnore +@PostMapping("/public/api") +``` + +## 总结 + +这次升级主要是为了让鉴权层更标准化。Sa-Token 这种国产框架确实在易用性和功能丰富度上找到了很好的平衡。通过 `UUID + Redis` 的模式，我们既保证了高性能，又拥有了完整的会话控制能力，非常适合此类单体或集群架构的项目。 diff --git a/src/main/java/cn/xf/basedemo/model/domain/SysMenu.java b/src/main/java/cn/xf/basedemo/model/domain/SysMenu.java index dd253c3..fc2109f 100644 --- a/src/main/java/cn/xf/basedemo/model/domain/SysMenu.java +++ b/src/main/java/cn/xf/basedemo/model/domain/SysMenu.java @@ -33,7 +33,7 @@ public class SysMenu implements Serializable { /** * 父菜单ID（sys_menu.parent_id，树结构） */ - private Long parent_id; + private Long parentId; /** * 菜单类型（sys_menu.type），0=目录,1=菜单,2=按钮 @@ -48,20 +48,20 @@ public class SysMenu implements Serializable { /** * 创建时间（sys_menu.create_time） */ - private Date create_time; + private Date createTime; /** * 创建人（sys_menu.create_by） */ - private String create_by; + private String createBy; /** * 更新时间（sys_menu.update_time） */ - private Date update_time; + private Date updateTime; /** * 更新人（sys_menu.update_by） */ - private String update_by; + private String updateBy; } \ No newline at end of file diff --git a/src/main/java/cn/xf/basedemo/model/domain/SysPermission.java b/src/main/java/cn/xf/basedemo/model/domain/SysPermission.java index 807d396..52a2ac5 100644 --- a/src/main/java/cn/xf/basedemo/model/domain/SysPermission.java +++ b/src/main/java/cn/xf/basedemo/model/domain/SysPermission.java @@ -33,25 +33,25 @@ public class SysPermission implements Serializable { /** * 所属菜单ID（sys_permission.menu_id） */ - private Long menu_id; + private Long menuId; /** * 创建时间（sys_permission.create_time） */ - private Date create_time; + private Date createTime; /** * 创建人（sys_permission.create_by） */ - private String create_by; + private String createBy; /** * 更新时间（sys_permission.update_time） */ - private Date update_time; + private Date updateTime; /** * 更新人（sys_permission.update_by） */ - private String update_by; + private String updateBy; } \ No newline at end of file diff --git a/src/main/java/cn/xf/basedemo/model/domain/SysRole.java b/src/main/java/cn/xf/basedemo/model/domain/SysRole.java index 5b0bf74..baf4e0e 100644 --- a/src/main/java/cn/xf/basedemo/model/domain/SysRole.java +++ b/src/main/java/cn/xf/basedemo/model/domain/SysRole.java @@ -38,21 +38,21 @@ public class SysRole implements Serializable { /** * 创建时间（sys_role.create_time） */ - private Date create_time; + private Date createTime; /** * 创建人（sys_role.create_by） */ - private String create_by; + private String createBy; /** * 更新时间（sys_role.update_time） */ - private Date update_time; + private Date updateTime; /** * 更新人（sys_role.update_by） */ - private String update_by; + private String updateBy; } \ No newline at end of file diff --git a/src/main/java/cn/xf/basedemo/model/domain/SysRoleMenu.java b/src/main/java/cn/xf/basedemo/model/domain/SysRoleMenu.java index 9803cf1..ce8e4f7 100644 --- a/src/main/java/cn/xf/basedemo/model/domain/SysRoleMenu.java +++ b/src/main/java/cn/xf/basedemo/model/domain/SysRoleMenu.java @@ -23,31 +23,31 @@ public class SysRoleMenu implements Serializable { /** * 角色ID（sys_role_menu.role_id） */ - private Long role_id; + private Long roleId; /** * 菜单ID（sys_role_menu.menu_id） */ - private Long menu_id; + private Long menuId; /** * 创建时间（sys_role_menu.create_time） */ - private Date create_time; + private Date createTime; /** * 创建人（sys_role_menu.create_by） */ - private String create_by; + private String createBy; /** * 更新时间（sys_role_menu.update_time） */ - private Date update_time; + private Date updateTime; /** * 更新人（sys_role_menu.update_by） */ - private String update_by; + private String updateBy; } \ No newline at end of file diff --git a/src/main/java/cn/xf/basedemo/model/domain/SysRolePermission.java b/src/main/java/cn/xf/basedemo/model/domain/SysRolePermission.java index 8b9138c..f2e5cfc 100644 --- a/src/main/java/cn/xf/basedemo/model/domain/SysRolePermission.java +++ b/src/main/java/cn/xf/basedemo/model/domain/SysRolePermission.java @@ -23,31 +23,31 @@ public class SysRolePermission implements Serializable { /** * 角色ID（sys_role_permission.role_id） */ - private Long role_id; + private Long roleId; /** * 权限ID（sys_role_permission.permission_id） */ - private Long permission_id; + private Long permissionId; /** * 创建时间（sys_role_permission.create_time） */ - private Date create_time; + private Date createTime; /** * 创建人（sys_role_permission.create_by） */ - private String create_by; + private String createBy; /** * 更新时间（sys_role_permission.update_time） */ - private Date update_time; + private Date updateTime; /** * 更新人（sys_role_permission.update_by） */ - private String update_by; + private String updateBy; } \ No newline at end of file diff --git a/src/main/java/cn/xf/basedemo/model/domain/SysUserRole.java b/src/main/java/cn/xf/basedemo/model/domain/SysUserRole.java index 306e5d0..53220ab 100644 --- a/src/main/java/cn/xf/basedemo/model/domain/SysUserRole.java +++ b/src/main/java/cn/xf/basedemo/model/domain/SysUserRole.java @@ -24,31 +24,31 @@ public class SysUserRole implements Serializable { /** * 用户ID（sys_user_role.user_id） */ - private Long user_id; + private Long userId; /** * 角色ID（sys_user_role.role_id） */ - private Long role_id; + private Long roleId; /** * 创建时间（sys_user_role.create_time） */ - private Date create_time; + private Date createTime; /** * 创建人（sys_user_role.create_by） */ - private String create_by; + private String createBy; /** * 更新时间（sys_user_role.update_time） */ - private Date update_time; + private Date updateTime; /** * 更新人（sys_user_role.update_by） */ - private String update_by; + private String updateBy; } \ No newline at end of file diff --git a/src/main/resources/mapper/SysMenuMapper.xml b/src/main/resources/mapper/SysMenuMapper.xml index 85ddb50..7993cc8 100644 --- a/src/main/resources/mapper/SysMenuMapper.xml +++ b/src/main/resources/mapper/SysMenuMapper.xml @@ -8,13 +8,13 @@ - + - - - - + + + + diff --git a/src/main/resources/mapper/SysPermissionMapper.xml b/src/main/resources/mapper/SysPermissionMapper.xml index bc68c48..f289814 100644 --- a/src/main/resources/mapper/SysPermissionMapper.xml +++ b/src/main/resources/mapper/SysPermissionMapper.xml @@ -8,11 +8,11 @@ - - - - - + + + + + diff --git a/src/main/resources/mapper/SysRoleMapper.xml b/src/main/resources/mapper/SysRoleMapper.xml index 2c92b14..78fa57c 100644 --- a/src/main/resources/mapper/SysRoleMapper.xml +++ b/src/main/resources/mapper/SysRoleMapper.xml @@ -9,10 +9,10 @@ - - - - + + + + diff --git a/src/main/resources/mapper/SysRoleMenuMapper.xml b/src/main/resources/mapper/SysRoleMenuMapper.xml index 663d0c3..038efb1 100644 --- a/src/main/resources/mapper/SysRoleMenuMapper.xml +++ b/src/main/resources/mapper/SysRoleMenuMapper.xml @@ -5,12 +5,12 @@ - - - - - - + + + + + + diff --git a/src/main/resources/mapper/SysRolePermissionMapper.xml b/src/main/resources/mapper/SysRolePermissionMapper.xml index 2b68d70..35412df 100644 --- a/src/main/resources/mapper/SysRolePermissionMapper.xml +++ b/src/main/resources/mapper/SysRolePermissionMapper.xml @@ -5,12 +5,12 @@ - - - - - - + + + + + + diff --git a/src/main/resources/mapper/SysUserRoleMapper.xml b/src/main/resources/mapper/SysUserRoleMapper.xml index 30caf1c..a4d3338 100644 --- a/src/main/resources/mapper/SysUserRoleMapper.xml +++ b/src/main/resources/mapper/SysUserRoleMapper.xml @@ -5,12 +5,12 @@ - - - - - - + + + + + +