身份认证与应用安全 / 系统课时

统一处理权限不足异常

统一处理权限不足异常

接口鉴权失败时,如果所有异常都返回同一个“无权限”结果,前端无法判断该引导登录、提示缺少角色,还是直接隐藏无权操作。本篇把 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 工程中,并确保它位于启动类可扫描的包路径。示例不把框架原始异常消息直接返回给前端,避免接口契约依赖内部文案。

java
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、堆栈或内部权限实现细节返回给客户端。

准备三个受保护接口做验证

片段示例:以下控制器分别触发登录、角色和权限校验,便于确认异常映射是否正确。

java
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。

bash
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>"

预期输出

text
请求 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。稳定的状态码和业务码能让权限策略调整、框架升级与前端交互相互解耦。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

统一处理权限不足异常

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通