Spring Boot 3 302 重定向处理方法

在 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 重定向：

1. 使用 HttpServletResponse.sendRedirect()：

   @GetMapping("/callback")
   public void callback(HttpServletResponse httpResponse) throws IOException {
       // ... 业务逻辑 ...
       httpResponse.addCookie(jwtTokenCookie); // 添加 Cookie
       httpResponse.sendRedirect(state.targetUri()); // 期望发送 302
   }

   这种方法在 Spring Boot 3 中可能无法按预期工作，而是被内部处理。

2. 使用 ResponseEntity 配合 HttpHeaders.setLocation()：

   @GetMapping("/callback")
   public ResponseEntity callback() 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”的理念，即确保服务器仅发送重定向响应，而不进行后续处理。