身份认证与应用安全 / 系统课时
统一处理未登录异常
统一处理未登录异常
路由拦截器负责判断请求是否已登录,但异常不应该直接变成框架堆栈或不稳定的错误文本。本节把 NotLoginException 集中交给 Spring Web 全局异常处理器,统一返回 HTTP 401、业务错误码和固定 JSON 结构。
学习目标
- 理解
NotLoginException从鉴权点传播到全局异常处理器的路径 - 用
@RestControllerAdvice统一返回稳定的未登录响应 - 通过无 Token 请求验证状态码和 JSON 结构
把异常收口到全局处理层
当路由拦截器执行 StpUtil.checkLogin() 时,未登录会抛出 NotLoginException。控制器不需要逐个捕获它,统一处理器负责把认证异常转换成对外协议,这样业务接口只关心正常逻辑。

这种收口方式还有一个重要边界:只处理明确的认证异常,不要用 Exception.class 把所有错误都包装成“未登录”,否则数据库异常、参数错误也会被误判。
返回稳定的 JSON 协议
下面的处理器可以直接放入已经接入 Sa-Token 的 Spring Boot 项目。它不把 e.getMessage() 原样返回给客户端,而是输出由应用定义的固定错误码和提示语。
package com.example.auth;
import cn.dev33.satoken.exception.NotLoginException;
import java.util.LinkedHashMap;
import java.util.Map;
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 GlobalExceptionHandler {
@ExceptionHandler(NotLoginException.class)
public ResponseEntity<Map<String, Object>> handleNotLogin(NotLoginException e) {
Map<String, Object> body = new LinkedHashMap<>();
body.put("code", 40101);
body.put("message", "未登录或登录状态已失效");
return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(body);
}
}生效后,任何由 Spring MVC 请求链抛出的 NotLoginException 都会进入这个方法。40101 是应用自己的业务码,可以换成团队已有规范;HTTP 状态码使用 401,便于网关、前端和监控统一识别认证失败。
用无 Token 请求验证
假设 /api/profile 已被路由拦截规则保护,在不携带 Token 的情况下发送请求:
curl -i http://localhost:<PORT>/api/profile预期输出的关键部分如下,实际 <PORT>、响应头顺序和日期等动态值可能不同。
HTTP/1.1 401
{"code":40101,"message":"未登录或登录状态已失效"}如果这里仍返回框架默认错误页或 500,先确认异常处理器是否处于 Spring 扫描路径,再确认抛出的确实是 NotLoginException,而不是其他异常类型。
不要把权限不足混成未登录
“没有登录”和“已经登录但没有权限”是两种不同状态。NotLoginException 只负责认证失败;权限校验失败应由对应的权限异常处理逻辑返回另一组业务码,前端才能决定是引导登录,还是展示“无权操作”。
统一异常处理的目标不是隐藏所有异常,而是把内部异常类型转换成稳定、最小且可观测的外部协议。这样路由拦截规则可以专注于鉴权,业务接口也不会重复编写认证失败响应。