Spring Boot实现404重定向至Swagger页面失败问题排查

1. 缺失关键配置 #

你仅配置了spring.mvc.throw-exception-if-no-handler-found=true，还需要补充以下配置：

# Spring Boot 2.x 版本
spring.resources.add-mappings=false
# Spring Boot 3.x 版本
spring.web.resources.add-mappings=false

原因：当请求匹配到静态资源路径（即使资源不存在），Spring默认不会抛出NoHandlerFoundException，而是直接返回404状态码，导致你的异常处理器无法捕获该异常。关闭资源自动映射后，所有未匹配到控制器的请求才会触发NoHandlerFoundException。

2. 异常处理器的正确实现 #

确保@ControllerAdvice的异常处理方法配置精准，以下是针对NoHandlerFoundException的示例代码：

import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.servlet.NoHandlerFoundException;
import org.springframework.web.servlet.view.RedirectView;

@ControllerAdvice
public class NotFoundExceptionHandler {

    @ExceptionHandler(NoHandlerFoundException.class)
    public RedirectView handleNotFound() {
        // 根据你的Swagger版本调整路径：Swagger2用/swagger-ui.html，SpringDoc用/swagger-ui/index.html
        return new RedirectView("/swagger-ui/index.html");
    }
}

注意：Spring Boot 3.x环境下，需确保引入的是org.springframework.web.servlet.NoHandlerFoundException类（根据依赖调整包路径）。

3. 验证Swagger访问路径 #

确认你的Swagger实际可访问路径，不同版本路径不同：

• Swagger 2.x：/swagger-ui.html
• SpringDoc OpenAPI（Spring Boot 3.x常用）：/swagger-ui/index.html
  若路径错误，重定向后仍会出现404，易让你误以为原方案无效。

4. 排除其他异常处理器干扰 #

如果项目中存在其他@ControllerAdvice或ExceptionHandler，检查它们的优先级是否高于你的404处理器。可通过@Order注解提升当前处理器的优先级：

import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.servlet.NoHandlerFoundException;
import org.springframework.web.servlet.view.RedirectView;

@ControllerAdvice
@Order(Ordered.HIGHEST_PRECEDENCE)
public class NotFoundExceptionHandler {

    @ExceptionHandler(NoHandlerFoundException.class)
    public RedirectView handleNotFound() {
        return new RedirectView("/swagger-ui/index.html");
    }
}

5. 修正ErrorController的范围问题 #

若你之前使用ErrorController导致403错误被错误重定向，可修改实现逻辑，仅针对404状态码跳转：

import org.springframework.boot.web.servlet.error.ErrorController;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

import javax.servlet.http.HttpServletRequest;

@Controller
public class CustomErrorController implements ErrorController {

    @RequestMapping("/error")
    public String handleError(HttpServletRequest request) {
        Object status = request.getAttribute("javax.servlet.error.status_code");
        if (status != null) {
            int statusCode = Integer.parseInt(status.toString());
            if (statusCode == HttpStatus.NOT_FOUND.value()) {
                return "redirect:/swagger-ui/index.html";
            }
        }
        // 其他状态码返回默认错误页
        return "forward:/error";
    }
}

内容的提问来源于stack exchange，提问作者Kira Resari