身份认证与应用安全 / 系统课时
用注解声明接口权限
用注解声明接口权限
当大量 Controller 都要手写 StpUtil.checkLogin()、checkRole() 或 checkPermission() 时,鉴权代码会挤进业务方法。Sa-Token 的注解鉴权可以把访问条件直接声明在接口上,由拦截器在进入方法前统一校验,让控制器只保留业务逻辑。
学习目标
- 能注册
SaInterceptor打开注解式鉴权 - 能使用
SaCheckLogin、SaCheckRole、SaCheckPermission声明访问条件 - 能判断多个鉴权注解组合时的实际约束
先启用注解鉴权
在 Spring MVC 项目中,仅给方法加注解还不够,需要把 SaInterceptor 注册到 MVC 拦截器链。当前官方文档说明,注册该拦截器后即可执行 Sa-Token 注解校验;SaCheckLogin 用于登录校验,SaCheckRole 用于角色校验,SaCheckPermission 用于权限校验。([GitHub][2])
注解鉴权发生在 Controller 方法执行之前,因此失败时不会进入方法体。它适合稳定的接口访问规则;如果权限条件来自复杂运行时数据,例如“只能修改自己创建的订单”,仍应在业务层补充资源级校验。
注解请求如何被拦截
请求先进入 SaInterceptor,框架读取目标类或方法上的鉴权注解,再根据当前会话执行登录、角色或权限校验。全部条件通过才调用 Controller;任一条件失败都会抛出对应鉴权异常。

在接口上声明三类条件
下面示例同时包含拦截器注册、登录入口、角色与权限数据提供器,以及三个受保护接口。前提是 Spring Boot 项目已经引入与自身版本匹配的 Sa-Token starter 和 Spring Web。
package com.example.annotationdemo;
import cn.dev33.satoken.annotation.SaCheckLogin;
import cn.dev33.satoken.annotation.SaCheckPermission;
import cn.dev33.satoken.annotation.SaCheckRole;
import cn.dev33.satoken.interceptor.SaInterceptor;
import cn.dev33.satoken.stp.StpInterface;
import cn.dev33.satoken.stp.StpUtil;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import java.util.List;
@SpringBootApplication
public class AnnotationDemoApplication {
public static void main(String[] args) {
SpringApplication.run(AnnotationDemoApplication.class, args);
}
@Configuration
static class SaTokenConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
// 注册后,Sa-Token 会在进入 Controller 前处理鉴权注解。
registry.addInterceptor(new SaInterceptor())
.addPathPatterns("/**");
}
}
@RestController
static class DemoController {
@PostMapping("/demo/login/{id}")
String login(@PathVariable long id) {
StpUtil.login(id);
return StpUtil.getTokenValue();
}
@SaCheckLogin
@GetMapping("/demo/profile")
String profile() {
return "profile-ok";
}
@SaCheckRole("admin")
@GetMapping("/demo/admin/report")
String report() {
return "report-ok";
}
@SaCheckPermission("user.delete")
@DeleteMapping("/demo/users/{id}")
String delete(@PathVariable long id) {
return "deleted:" + id;
}
}
@Component
static class PermissionProvider implements StpInterface {
@Override
public List<String> getPermissionList(Object loginId, String loginType) {
return "1".equals(String.valueOf(loginId))
? List.of("user.read", "user.delete")
: List.of("user.read");
}
@Override
public List<String> getRoleList(Object loginId, String loginType) {
return "1".equals(String.valueOf(loginId))
? List.of("admin")
: List.of("user");
}
}
}启动应用并登录账号 1 后,把返回的真实 Token 替换 <TOKEN>;实际端口替换 <PORT>。
curl -X POST http://localhost:<PORT>/demo/login/1
curl -H "satoken: <TOKEN>" http://localhost:<PORT>/demo/profile
curl -H "satoken: <TOKEN>" http://localhost:<PORT>/demo/admin/report
curl -X DELETE -H "satoken: <TOKEN>" http://localhost:<PORT>/demo/users/7预期输出
<TOKEN>
profile-ok
report-ok
deleted:7账号 2 登录后仍能通过 SaCheckLogin,但访问管理员报表会触发角色校验失败,删除用户会触发权限校验失败。异常最终被转换成什么 HTTP 状态码与响应体,取决于项目的全局异常处理策略。
组合注解时确认 AND 与 OR
同一个方法同时声明多个鉴权注解时,默认效果是这些条件都要满足。例如同时标记 SaCheckLogin、SaCheckRole("admin") 和 SaCheckPermission("user.delete"),意味着登录、角色、权限三项都通过才会进入方法。
SaCheckPermission 或 SaCheckRole 自身包含多个值时,默认模式是 SaMode.AND;若业务要求“多个权限满足任意一个即可”,可显式设置 mode = SaMode.OR。不要为了方便把所有接口都改成 OR,否则会在不经意间放宽访问条件。
注解适合表达接口级、静态且易审计的规则;涉及“当前账号是否拥有这条具体数据”的资源归属判断,应继续留在业务层。把两者分开,既能减少重复鉴权代码,也不会把动态授权逻辑硬塞进注解。