spring security的认证与授权异常发生在控制器层之前，无法被`@controlleradvice`捕获。本文将指导如何通过实现`authenticationentrypoint`和`accessdeniedhandler`接口，在spring security过滤器链中定制认证失败和授权拒绝的响应体。通过采用委托模式（delegate approach），可以将这些异常转发给spring mvc的`handlerexceptionresolver`处理，从而利用`@controlleradvice`统一生成友好的json错误信息，提升api的用户体验和错误处理一致性。
Spring Security异常处理机制概述
在Spring Boot应用中，我们通常会使用@ControllerAdvice结合@ExceptionHandler来集中处理控制器层抛出的各种异常，并返回统一的JSON错误响应。然而，Spring Security的过滤器链（Filter Chain）在请求到达控制器之前就已经执行。这意味着，如果在认证（Authentication）或授权（Authorization）阶段发生异常，例如用户未提供有效的凭证（AuthenticationException）或已认证用户但无权访问某个资源（AccessDeniedException），这些异常将不会被@ControllerAdvice捕获。
Spring Security通过ExceptionTranslationFilter来处理这些发生在过滤器链中的特定异常。当ExceptionTranslationFilter捕获到AuthenticationException或AccessDeniedException时，它会委托给相应的处理器来生成响应：
- 对于AuthenticationException（例如，用户未登录或提供的凭证无效），ExceptionTranslationFilter会调用配置的AuthenticationEntryPoint。
- 对于AccessDeniedException（例如，已登录用户尝试访问其无权访问的资源），ExceptionTranslationFilter会调用配置的AccessDeniedHandler。
默认情况下，这些处理器可能会重定向到登录页面或返回简单的HTTP状态码。为了实现API风格的JSON错误响应，我们需要自定义这些处理器。
定制认证失败响应：AuthenticationEntryPoint
AuthenticationEntryPoint接口定义了一个commence方法，当未认证用户尝试访问受保护资源，或认证过程中发生异常时，此方法会被调用。
直接写入响应体
最直接的方式是在commence方法中手动构建JSON并写入HttpServletResponse。
import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.stereotype.Component;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
@Component
public class CustomAuthenticationEntryPoint implements AuthenticationEntryPoint {
private final ObjectMapper objectMapper = new ObjectMapper();
@Override
public void commence(HttpServletRequest request, HttpServletResponse response,
AuthenticationException authException) throws IOException, ServletException {
response.setStatus(HttpStatus.UNAUTHORIZED.value());
response.setContentType(MediaType.APPLICATION_JSON_VALUE);
response.setCharacterEncoding("UTF-8");
Map errorDetails = new HashMap<>();
errorDetails.put("status", HttpStatus.UNAUTHORIZED.value());
errorDetails.put("error", "Unauthorized");
errorDetails.put("message", "认证失败: " + authException.getMessage());
errorDetails.put("path", request.getRequestURI());
response.getWriter().write(objectMapper.writeValueAsString(errorDetails));
}
} 委托模式（Delegate Approach）
为了保持错误处理的一致性并利用@ControllerAdvice的强大功能（如统一的JSON序列化、国际化等），推荐使用委托模式。这种方法通过将异常重新转发给Spring MVC的HandlerExceptionResolver，使得@ControllerAdvice中的@ExceptionHandler能够捕获并处理这些异常。
首先，定义一个简单的错误响应DTO：
public class ErrorResponse {
private String code;
private String message;
private int status;
public ErrorResponse(String code, String message, int status) {
this.code = code;
this.message = message;
this.status = status;
}
// Getters and Setters
public String getCode() { return code; }
public void setCode(String code) { this.code = code; }
public String getMessage() { return message; }
public void setMessage(String message) { this.message = message; }
public int getStatus() { return status; }
public void setStatus(int status) { this.status = status; }
}然后，创建自定义的AuthenticationEntryPoint，注入HandlerExceptionResolver：
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerExceptionResolver;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
@Component
public class RestAuthenticationEntryPoint implements AuthenticationEntryPoint {
private final HandlerExceptionResolver handlerExceptionResolver;
// 注入Spring MVC的HandlerExceptionResolver，通常是ExceptionHandlerExceptionResolver
public RestAuthenticationEntryPoint(@Qualifier("handlerExceptionResolver") HandlerExceptionResolver handlerExceptionResolver) {
this.handlerExceptionResolver = handlerExceptionResolver;
}
@Override
public void commence(HttpServletRequest request, HttpServletResponse response,
AuthenticationException authException) throws IOException, ServletException {
// 将AuthenticationException委托给HandlerExceptionResolver处理
// 这样，@ControllerAdvice中的@ExceptionHandler就能捕获到这个异常
handlerExceptionResolver.resolveException(request, response, null, authException);
}
}注意：@Qualifier("handlerExceptionResolver")确保注入的是Spring MVC用于处理@ExceptionHandler的那个HandlerExceptionResolver实例。
定制授权拒绝响应：AccessDeniedHandler
AccessDeniedHandler接口定义了一个handle方法，当已认证用户尝试访问其没有权限的资源时，此方法会被调用。
与AuthenticationEntryPoint类似，我们可以选择直接写入响应体或使用委托模式。为了保持一致性，同样推荐使用委托模式。
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.security.web.access.AccessDeniedHandler;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerExceptionResolver;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
@Component
public class RestAccessDeniedHandler implements AccessDeniedHandler {
private final HandlerExceptionResolver handlerExceptionResolver;
public RestAccessDeniedHandler(@Qualifier("handlerExceptionResolver") HandlerExceptionResolver handlerExceptionResolver) {
this.handlerExceptionResolver = handlerExceptionResolver;
}
@Override
public void handle(HttpServletRequest request, HttpServletResponse response,
AccessDeniedException accessDeniedException) throws IOException, ServletException {
// 将AccessDeniedException委托给HandlerExceptionResolver处理
handlerExceptionResolver.resolveException(request, response, null, accessDeniedException);
}
}全局异常处理器：@ControllerAdvice
在实现了委托模式后，我们需要一个@ControllerAdvice来捕获这些被转发的异常，并生成统一的JSON响应。
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.security.core.AuthenticationException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(AuthenticationException.class)
@ResponseStatus(HttpStatus.UNAUTHORIZED)
public ResponseEntity handleAuthenticationException(AuthenticationException ex) {
// 根据AuthenticationException类型和信息构建具体的ErrorResponse
return new ResponseEntity<>(new ErrorResponse("AUTH_001", "认证失败: " + ex.getMessage(), HttpStatus.UNAUTHORIZED.value()), HttpStatus.UNAUTHORIZED);
}
@ExceptionHandler(AccessDeniedException.class)
@ResponseStatus(HttpStatus.FORBIDDEN)
public ResponseEntity handleAccessDeniedException(AccessDeniedException ex) {
// 根据AccessDeniedException类型和信息构建具体的ErrorResponse
return new ResponseEntity<>(new ErrorResponse("AUTH_002", "权限不足: " + ex.getMessage(), HttpStatus.FORBIDDEN.value()), HttpStatus.FORBIDDEN);
}
// 可以添加其他通用异常处理器
@ExceptionHandler(Exception.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public ResponseEntity handleGenericException(Exception ex) {
return new ResponseEntity<>(new ErrorResponse("SYS_001", "系统内部错误: " + ex.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR.value()), HttpStatus.INTERNAL_SERVER_ERROR);
}
} Spring Security配置整合
最后一步是将自定义的AuthenticationEntryPoint和AccessDeniedHandler注册到Spring Security的配置中。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;
@Configuration
@EnableWebSecurity
public class SecurityConfig {
private final RestAuthenticationEntryPoint authenticationEntryPoint;
private final RestAccessDeniedHandler accessDeniedHandler;
// 注入自定义的处理器
public SecurityConfig(RestAuthenticationEntryPoint authenticationEntryPoint,
RestAccessDeniedHandler accessDeniedHandler) {
this.authenticationEntryPoint = authenticationEntryPoint;
this.accessDeniedHandler = accessDeniedHandler;
}
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
.csrf(csrf -> csrf.disable()) // 通常RESTful API会禁用CSRF
.authorizeHttpRequests(authorize -> authorize
.antMatchers("/public/**").permitAll() // 允许公共访问的路径
.anyRequest().authenticated() // 其他所有请求需要认证
)
.exceptionHandling(exceptionHandling -> exceptionHandling
.authenticationEntryPoint(authenticationEntryPoint) // 配置认证失败处理器
.accessDeniedHandler(accessDeniedHandler) // 配置授权拒绝处理器
)
.sessionManagement(session -> session
.sessionCreationPolicy(SessionCreationPolicy.STATELESS) // RESTful API通常无状态
);
return http.build();
}
}总结
通过上述步骤，我们成功地在Spring Security过滤器链中定制了认证失败和授权拒绝的响应体。采用委托模式，将AuthenticationException和AccessDeniedException转发给HandlerExceptionResolver，使得@ControllerAdvice能够统一处理这些异常，从而确保API在任何错误场景下都能返回一致、友好的JSON错误响应。这种方法极大地提升了API的健壮性和可维护性，为前端应用提供了统一的错误处理机制。
