在 spring boot 3 升级后，开发者可能会遇到一个问题：原本旨在返回 302 重定向状态码的接口，却被 spring 内部处理并直接返回了目标 uri 的内容，而非期望的重定向响应。本文将深入探讨这一现象，分析其可能的原因，并提供一个通过自定义异常和全局异常处理器来强制返回 302 状态码的专业解决方案，确保客户端能够正确接收重定向指令。
问题描述：Spring Boot 3 中的 302 重定向行为异常
在 Spring Boot 3 环境中，当一个控制器方法尝试通过 HttpServletResponse.sendRedirect() 或 ResponseEntity 配合 HttpHeaders.setLocation() 来发送一个 302 (Found) 重定向响应时，系统可能不会如预期般将 302 状态码返回给客户端。相反，Spring 框架似乎在服务器内部执行了重定向操作，并直接返回了目标 URI 对应的资源内容。这意味着客户端不会收到 302 状态码及 Location 头，而是直接获取到重定向目标的内容，这与期望的外部服务重定向行为不符。
开发者在尝试解决此问题时，即使配置 TestRestTemplate 禁用客户端重定向，也无法观察到 302 状态码，进一步证实了问题出在服务器端。通过开启 TRACE 级别的日志，可以发现 FilterChainProxy 在 DispatcherServlet 完成 302 响应后，再次尝试匹配请求并处理重定向，这表明 Spring Security 或其他过滤器链中的组件可能在拦截并内部处理 3xx 响应。
初始尝试与诊断
为了明确问题，开发者通常会尝试以下几种方式来触发 302 重定向：
-
使用 HttpServletResponse.sendRedirect()：
@GetMapping("/callback") public void callback(HttpServletResponse httpResponse) throws IOException { // ... 业务逻辑 ... httpResponse.addCookie(jwtTokenCookie); // 添加 Cookie httpResponse.sendRedirect(state.targetUri()); // 期望发送 302 }这种方法在 Spring Boot 3 中可能无法按预期工作，而是被内部处理。
-
使用 ResponseEntity 配合 HttpHeaders.setLocation()：
@GetMapping("/callback") public ResponseEntitycallback() throws URISyntaxException { // ... 业务逻辑 ... HttpHeaders httpHeaders = new HttpHeaders(); httpHeaders.setLocation(new URI(ssoState.targetUri())); // 注意：这里无法直接添加 HttpServletResponse 的 Cookie，需要通过 Set-Cookie 头 // httpHeaders.add(HttpHeaders.SET_COOKIE, "cookieName=cookieValue; Path=/; HttpOnly"); return new ResponseEntity<>(httpHeaders, HttpStatus.FOUND); // 期望发送 302 } 即使采用这种更 Spring 风格的方式，问题依然存在，表明并非简单的 API 使用不当。
日志分析： 开启 TRACE 级别的日志后，可以观察到以下关键信息：
- DispatcherServlet 确实完成了 302 FOUND 响应。
- 随后，FilterChainProxy 再次介入，尝试匹配请求并处理 /api/accounts (即重定向目标) 的内容。
这强烈暗示在 DispatcherServlet 发出 302 响应之后，Spring Security 的 FilterChainProxy 或其他自定义过滤器在响应被发送到客户端之前，拦截了该 3xx 响应并触发了内部的请求转发。
解决方案：通过自定义异常和全局异常处理器强制重定向
为了绕过这种内部重定向行为，我们可以采用一种策略，即在控制器方法中不直接发送重定向，而是抛出一个自定义异常。然后，通过全局异常处理器 (@ControllerAdvice) 捕获这个异常，并在异常处理器中显式地构建并返回一个包含 302 状态码和 Location 头的 ResponseEntity。这种方式能够确保响应在 Spring 过滤器链的更后期阶段被精确控制，从而避免被意外拦截。
1. 定义自定义重定向异常
首先，创建一个自定义的 RuntimeException，用于携带重定向目标 URI 和任何需要随重定向一起发送的 Set-Cookie 头信息。
import java.util.Collections;
import java.util.List;
public class RedirectException extends RuntimeException {
private final String targetUri;
private final List setCookieHeaders; // 用于携带 Set-Cookie 头的值
public RedirectException(String targetUri) {
this(targetUri, Collections.emptyList());
}
public RedirectException(String targetUri, List setCookieHeaders) {
super("Redirect to " + targetUri);
this.targetUri = targetUri;
this.setCookieHeaders = setCookieHeaders;
}
public String getTargetUri() {
return targetUri;
}
public List getSetCookieHeaders() {
return setCookieHeaders;
}
} 2. 修改控制器方法抛出异常
在需要进行重定向的控制器方法中，不再调用 sendRedirect 或返回 ResponseEntity，而是抛出上面定义的 RedirectException。
import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.validation.constraints.NotNull;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import lombok.SneakyThrows; // 如果使用 Lombok
import java.util.Collections;
import java.util.List;
@RestController
public class SsoController {
// 假设 cookieService 和 userContext 已经定义
// private final CookieService cookieService;
// private final UserContext userContext;
@GetMapping("/callback")
@SneakyThrows // 简化异常处理，实际项目中应更精细处理
public void callback(@NotNull @RequestParam(name = "code") String authorizationCode,
@NotNull @RequestParam(name = "state") String state,
HttpServletResponse httpResponse) { // 尽管不直接用sendRedirect，但可能需要创建Cookie
try {
// ... 业务逻辑，例如验证授权码，获取用户上下文 ...
// userContext = ...;
// 假设 cookieService.createJwtCookie 返回一个 jakarta.servlet.http.Cookie
// Cookie jwtTokenCookie = cookieService.createJwtCookie(userContext);
// 示例：手动创建一个 Cookie
Cookie jwtTokenCookie = new Cookie("jwtToken", "some_jwt_value");
jwtTokenCookie.setPath("/");
jwtTokenCookie.setHttpOnly(true);
jwtTokenCookie.setMaxAge(3600); // 1小时
// 将 Cookie 转换为 Set-Cookie 头字符串，以便通过异常传递
String setCookieHeader = String.format("%s=%s; Path=%s; HttpOnly; Max-Age=%d",
jwtTokenCookie.getName(),
jwtTokenCookie.getValue(),
jwtTokenCookie.getPath(),
jwtTokenCookie.getMaxAge());
// 抛出自定义重定向异常，包含目标 URI 和 Set-Cookie 头
throw new RedirectException(state.targetUri(), Collections.singletonList(setCookieHeader));
} catch (IntegrationException e) { // 假设存在业务集成异常
throw new ControllerException(BAD_REQUEST, e); // 抛出其他业务异常
}
}
}3. 创建全局异常处理器
创建一个 @ControllerAdvice 类，其中包含一个 @ExceptionHandler 方法来捕获 RedirectException。在这个处理器中，我们将手动构建 ResponseEntity，设置 302 状态码、Location 头和任何 Set-Cookie 头。
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import java.net.URI;
import java.net.URISyntaxException;
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(RedirectException.class)
public ResponseEntity handleRedirectException(RedirectException ex) throws URISyntaxException {
HttpHeaders headers = new HttpHeaders();
headers.setLocation(new URI(ex.getTargetUri()));
// 添加从异常中获取的 Set-Cookie 头
ex.getSetCookieHeaders().forEach(cookieHeader -> headers.add(HttpHeaders.SET_COOKIE, cookieHeader));
// 返回包含 302 状态码和 Location 头的 ResponseEntity
return new ResponseEntity<>(headers, HttpStatus.FOUND);
}
// 可以添加其他异常处理器
// @ExceptionHandler(ControllerException.class)
// public ResponseEntity handleControllerException(ControllerException ex) {
// return new ResponseEntity<>(ex.getMessage(), ex.getHttpStatus());
// }
} 解决方案原理与优势
这种方法的关键在于：
- 绕过中间过滤器： 当控制器方法抛出异常时，Spring 的异常处理机制会介入。@ControllerAdvice 中的 @ExceptionHandler 会在更晚的阶段处理请求，通常在大部分常规过滤器（包括可能导致内部重定向的 Spring Security 过滤器）之后。这使得我们能够更直接地控制最终的 HTTP 响应。
- 显式构建响应： 在异常处理器中，我们使用 ResponseEntity 显式地设置 HTTP 状态码 (HttpStatus.FOUND) 和 Location 头。这确保了服务器发送的响应只包含重定向所需的指令，而不会尝试内部处理目标 URI 的内容。
- 包含必要头信息： 通过在 RedirectException 中携带 Set-Cookie 头信息，并由异常处理器将其添加到 ResponseEntity 中，我们可以确保重定向响应中包含所有必要的客户端状态信息。
这种方法符合“OnlyIn exchange pattern on your redirect”的理念，即确保服务器仅发送重定向响应，而不进行后续处理。
