Spring Boot中如何统一处理HTTP 401未授权异常？

Question

在Spring Boot应用中，如何统一处理HTTP 401未授权异常，确保所有未授权访问返回一致的响应格式？

Answer 1

在Spring Boot应用中，如何统一处理HTTP 401未授权异常，确保所有未授权访问返回一致的响应格式？

1. 异常处理的背景与意义

在构建RESTful API时，统一的异常响应格式对于前后端协作至关重要。HTTP 401异常通常表示请求缺少有效的身份验证凭证，常见于JWT鉴权、OAuth2等场景。若未统一处理，不同模块可能返回不同的错误结构，导致前端难以统一解析。

2. 常见处理方式对比

处理方式	优点	缺点
@ControllerAdvice	全局捕获异常，统一处理逻辑	需要手动处理不同异常类型
自定义过滤器	可在进入Controller前处理	实现较复杂，需理解过滤器链
Spring Security内置机制	与安全框架无缝集成	配置复杂，需熟悉安全机制

3. 实现方案详解

以下是一个基于Spring Security的全局异常处理示例：

3.1 自定义异常响应结构

public class ErrorResponse {
    private int status;
    private String message;
    private LocalDateTime timestamp;

    // 构造方法、getters and setters
}
    

3.2 使用@ControllerAdvice统一处理

@ControllerAdvice
public class AuthExceptionAdvice {

    @ExceptionHandler(UnauthorizedException.class)
    public ResponseEntity handleUnauthorizedException() {
        ErrorResponse error = new ErrorResponse();
        error.setStatus(HttpStatus.UNAUTHORIZED.value());
        error.setMessage("未授权访问");
        error.setTimestamp(LocalDateTime.now());

        return new ResponseEntity<>(error, HttpStatus.UNAUTHORIZED);
    }
}
    

3.3 在Spring Security中处理401异常

当使用Spring Security时，可以通过实现AuthenticationEntryPoint接口来自定义未授权访问的响应。

@Component
public class JwtAuthenticationEntryPoint implements AuthenticationEntryPoint {

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response,
                         AuthenticationException authException) throws IOException {
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
        response.setContentType("application/json");
        response.getWriter().write("{\"status\":401,\"message\":\"未授权访问\"}");
    }
}
    

4. 完整流程图

graph TD
            A[客户端发起请求] --> B{是否通过认证?}
            B -- 是 --> C[正常处理业务逻辑]
            B -- 否 --> D[触发AuthenticationEntryPoint]
            D --> E[返回统一格式的401响应]

5. 最佳实践建议

• 统一使用ErrorResponse类封装所有异常信息
• 在@ControllerAdvice中处理业务逻辑抛出的未授权异常
• 在Spring Security配置中设置自定义的AuthenticationEntryPoint
• 日志记录应包含请求路径、用户信息等上下文信息
• 考虑使用@ResponseStatus注解定义自定义异常类型