身份认证与应用安全 / 系统课时
统一处理权限不足异常
统一处理权限不足异常
接口鉴权失败时,如果所有异常都返回同一个“无权限”结果,前端无法判断该引导登录、提示缺少角色,还是直接隐藏无权操作。本篇把 Sa-Token 的三类常见授权异常映射为稳定的 HTTP 状态和业务错误码。
学习目标
- 区分
NotLoginException、NotRoleException与NotPermissionException - 使用全局异常处理器固定授权失败响应格式
- 用请求验证 401 与 403 的边界是否符合预期
先区分认证失败与授权失败
身份无效属于“还没有可用身份”,适合返回 HTTP 401;已经登录但角色或权限不足属于“身份有效但无权访问”,适合返回 HTTP 403。前端再通过稳定的业务 code 做细分,而不是解析异常文本。
| 异常 | HTTP 状态 | 建议业务码 | 前端动作 |
|---|---|---|---|
NotLoginException |
401 | AUTH_REQUIRED |
重新登录或刷新认证状态 |
NotRoleException |
403 | ROLE_REQUIRED |
提示当前角色不可访问 |
NotPermissionException |
403 | PERMISSION_DENIED |
提示缺少操作权限 |
NotLoginException 还可能表示 token 过期、被顶下线或被踢下线等登录失效场景。如果前端确实需要进一步区分,可以再读取异常的场景值;没有这类需求时,统一映射为认证失效即可。([GitHub][2])
用全局异常处理器固定响应格式
片段示例:把下面的类放入 Spring Boot 工程中,并确保它位于启动类可扫描的包路径。示例不把框架原始异常消息直接返回给前端,避免接口契约依赖内部文案。
package com.example.auth;
import cn.dev33.satoken.exception.NotLoginException;
import cn.dev33.satoken.exception.NotPermissionException;
import cn.dev33.satoken.exception.NotRoleException;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice
public class SaTokenExceptionHandler {
@ExceptionHandler(NotLoginException.class)
public ResponseEntity<AuthError> handleNotLogin(NotLoginException e) {
return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
.body(new AuthError(
"AUTH_REQUIRED",
"登录状态无效或不存在"
));
}
@ExceptionHandler(NotRoleException.class)
public ResponseEntity<AuthError> handleNotRole(NotRoleException e) {
return ResponseEntity.status(HttpStatus.FORBIDDEN)
.body(new AuthError(
"ROLE_REQUIRED",
"当前账号缺少所需角色"
));
}
@ExceptionHandler(NotPermissionException.class)
public ResponseEntity<AuthError> handleNotPermission(
NotPermissionException e
) {
return ResponseEntity.status(HttpStatus.FORBIDDEN)
.body(new AuthError(
"PERMISSION_DENIED",
"当前账号缺少所需权限"
));
}
public static class AuthError {
private final String code;
private final String message;
public AuthError(String code, String message) {
this.code = code;
this.message = message;
}
public String getCode() {
return code;
}
public String getMessage() {
return message;
}
}
}处理器生效后,业务接口无需重复捕获这三类异常。日志中可以记录异常类型和必要上下文,但响应体保持稳定,不要把 token、堆栈或内部权限实现细节返回给客户端。
准备三个受保护接口做验证
片段示例:以下控制器分别触发登录、角色和权限校验,便于确认异常映射是否正确。
package com.example.auth;
import cn.dev33.satoken.annotation.SaCheckLogin;
import cn.dev33.satoken.annotation.SaCheckPermission;
import cn.dev33.satoken.annotation.SaCheckRole;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/auth-demo")
public class AuthDemoController {
@GetMapping("/login")
@SaCheckLogin
public String loginOnly() {
return "login passed";
}
@GetMapping("/role")
@SaCheckRole("admin")
public String adminOnly() {
return "role passed";
}
@GetMapping("/permission")
@SaCheckPermission("report:export")
public String exportOnly() {
return "permission passed";
}
}使用下面的请求验证。假设 <TOKEN> 是有效登录令牌,但它既没有 admin 角色,也没有 report:export 权限;若项目修改了 token 名称,请替换请求头中的 satoken。
curl -i "http://localhost:<PORT>/auth-demo/login"
curl -i "http://localhost:<PORT>/auth-demo/role" -H "satoken: <TOKEN>"
curl -i "http://localhost:<PORT>/auth-demo/permission" -H "satoken: <TOKEN>"预期输出
请求 1:
HTTP/1.1 401
{"code":"AUTH_REQUIRED","message":"登录状态无效或不存在"}
请求 2:
HTTP/1.1 403
{"code":"ROLE_REQUIRED","message":"当前账号缺少所需角色"}
请求 3:
HTTP/1.1 403
{"code":"PERMISSION_DENIED","message":"当前账号缺少所需权限"}<PORT> 与 <TOKEN> 的实际值会随运行环境变化。只要状态码和业务 code 与上述语义一致,就说明异常分流已经生效。
让前端只依赖稳定契约
前端应把 HTTP 状态用于大类处理,再用 code 做业务分支。例如 401 统一进入重新认证流程,403 保留当前页面并提示权限不足;是否展示某个按钮仍可依据权限数据,但不能把“按钮隐藏”当成服务端鉴权的替代品。
不要用异常中文消息作为判断条件,也不要把所有 Sa-Token 异常统一转换成 500。稳定的状态码和业务码能让权限策略调整、框架升级与前端交互相互解耦。