本文旨在解决Spring Boot应用中，Spring Security过滤器链抛出的认证（`AuthenticationException`）和授权（`AccessDeniedException`）异常无法被全局异常处理器捕获的问题。我们将深入探讨如何通过实现自定义的`AuthenticationEntryPoint`和`AccessDeniedHandler`接口，在这些安全层级异常发生时，生成结构化的JSON响应体，从而提升用户体验并简化客户端错误处理。
Spring Security过滤器链中的异常处理机制
在Spring Boot应用中，我们通常会通过@ControllerAdvice结合@ExceptionHandler来构建一个全局的异常处理器，以统一处理控制器层抛出的各种异常，并返回友好的JSON错误信息。然而，当涉及到Spring Security的认证（Authentication）和授权（Authorization）失败时，这种机制往往无法生效。
其核心原因在于Spring Security的过滤器链在请求到达任何控制器之前就已经执行。如果在这个阶段发生认证失败（如用户未提供凭据或凭据无效）或授权失败（如用户无权访问特定资源），异常会在过滤器链中被捕获并处理，而不会传递到控制器层，因此也就不会触发@ControllerAdvice中定义的@ExceptionHandler。
默认情况下，Spring Security对于认证失败可能会在响应头中添加WWW-Authenticate信息，但响应体通常是空的或包含一个简单的HTML错误页面。对于现代的RESTful API而言，客户端更期望收到一个结构化的JSON错误响应，以便于解析和展示。为了实现这一目标，我们需要利用Spring Security提供的特定接口来定制这些安全层级的异常响应。
Spring Security主要处理两种类型的安全异常：
- AuthenticationException：当用户尝试访问受保护资源但尚未认证（或认证失败）时抛出。例如，请求头中缺少Authorization令牌，或者令牌无效。
- AccessDeniedException：当已认证的用户尝试访问其没有权限的资源时抛出。例如，用户已登录，但其角色不足以访问某个特定API。
定制认证失败响应：实现AuthenticationEntryPoint
AuthenticationEntryPoint接口用于处理AuthenticationException，即当用户尝试访问安全资源但尚未认证（或认证失败）时被调用。它定义了一个commence方法，允许我们自定义响应行为。
基本实现
以下是一个简单的AuthenticationEntryPoint实现，它直接向响应中写入一个JSON错误消息：
import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.http.MediaType;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.stereotype.Component;
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(HttpServletResponse.SC_UNAUTHORIZED); // 设置HTTP状态码为401
response.setContentType(MediaType.APPLICATION_JSON_VALUE); // 设置响应内容类型为JSON
response.setCharacterEncoding("UTF-8");
Map<String, Object> errorDetails = new HashMap<>();
errorDetails.put("timestamp", System.currentTimeMillis());
errorDetails.put("status", HttpServletResponse.SC_UNAUTHORIZED);
errorDetails.put("error", "Unauthorized");
errorDetails.put("message", "Authentication failed: " + authException.getMessage());
errorDetails.put("path", request.getRequestURI());
response.getWriter().write(objectMapper.writeValueAsString(errorDetails));
}
}结合@ExceptionHandler的委托模式
为了保持错误响应格式的一致性，我们可以让AuthenticationEntryPoint委托给Spring的HandlerExceptionResolver机制，从而间接触发我们全局@ControllerAdvice中的@ExceptionHandler。这种方法更加优雅，避免了在多个地方重复编写错误响应的序列化逻辑。
首先，我们需要在@ControllerAdvice中定义一个处理AuthenticationException的方法：
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.core.AuthenticationException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import java.util.HashMap;
import java.util.Map;
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(AuthenticationException.class)
public ResponseEntity<Map<String, Object>> handleAuthenticationException(AuthenticationException ex) {
Map<String, Object> errorDetails = new HashMap<>();
errorDetails.put("timestamp", System.currentTimeMillis());
errorDetails.put("status", HttpStatus.UNAUTHORIZED.value());
errorDetails.put("error", "Authentication Error");
errorDetails.put("message", "Invalid credentials or token: " + ex.getMessage());
// 可以添加更多自定义字段
return new ResponseEntity<>(errorDetails, HttpStatus.UNAUTHORIZED);
}
// 其他异常处理方法...
}然后，修改CustomAuthenticationEntryPoint，使其委托给HandlerExceptionResolver：
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
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 java.io.IOException;
@Component("delegatedAuthenticationEntryPoint") // 指定bean名称，避免与默认的AuthenticationEntryPoint冲突
public class DelegatedAuthentication 
