当前位置： 首页 > news >正文

Spring Boot中自定义404异常处理问题学习笔记

news 来源：原创 2025/4/25 12:47:34

1. 问题背景

在Spring Boot项目中，需要手动返回404异常给前端。为此，我创建了一个自定义的404异常类UnauthorizedAccessException，并在全局异常处理器GlobalExceptionHandler中处理该异常。然而，在使用Postman测试时，返回的仍然是500错误，而不是预期的404错误。

2. 代码实现

2.1 自定义404异常类

package cn.jbolt.config.exception;import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ResponseStatus;/*** 自定义无权限访问的异常*/
@ResponseStatus(HttpStatus.NOT_FOUND)
public class UnauthorizedAccessException extends RuntimeException {private final HttpStatus status;public UnauthorizedAccessException(String message) {super(message);this.status = HttpStatus.NOT_FOUND;}public HttpStatus getStatus() {return status;}
}

2.2 全局异常处理器

package cn.jbolt.config.exception;import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;@RestControllerAdvice
public class GlobalExceptionHandler {@ExceptionHandler(UnauthorizedAccessException.class)public ResponseEntity<String> handleUnauthorizedAccessException(UnauthorizedAccessException ex) {System.out.println("UnauthorizedAccessException-------------------------: " + ex.getMessage());HttpStatus status = ex.getStatus();String message = ex.getMessage();return new ResponseEntity<>(message, status);}
}

2.3 过滤器中抛出自定义异常

package cn.jbolt.teaching_tools.school;import cn.jbolt.config.exception.UnauthorizedAccessException;
import cn.jbolt.teaching_tools.school.entity.School;
import cn.jbolt.teaching_tools.school.service.SchoolService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class SchoolContextFilter implements Filter {@Autowiredprivate SchoolService schoolService;@Overridepublic void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)throws IOException, ServletException {HttpServletRequest httpRequest = (HttpServletRequest) request;HttpServletResponse httpResponse = (HttpServletResponse) response;try {// 从域名获取学校信息String serverName = httpRequest.getServerName();String[] domainParts = serverName.split("\\.");if (domainParts.length >= 3) {String subdomain = domainParts[0];// 查询学校IDSchool school = schoolService.getByDomain(subdomain);if (school != null) {// 设置到SchoolContextHolder和请求属性SchoolContextHolder.setSchoolId(school.getId().toString());} else {// 如果找不到学校，抛出异常throw new UnauthorizedAccessException("异常域名");}} else {// 如果不是二级域名，抛出异常throw new UnauthorizedAccessException("异常域名");}chain.doFilter(request, response);} catch (UnauthorizedAccessException ex) {// 手动处理异常，写入响应httpResponse.setStatus(HttpStatus.NOT_FOUND.value());httpResponse.setContentType("application/json;charset=UTF-8");httpResponse.getWriter().write("{\"timestamp\": " + System.currentTimeMillis() + ", \"status\": 404, \"error\": \"Not Found\", \"message\": \"" + ex.getMessage() + "\", \"path\": \"" + httpRequest.getRequestURI() + "\"}");} finally {SchoolContextHolder.clear();}}
}

3. 问题分析

3.1 Filter抛出的异常未被Spring MVC捕获

在Spring Boot中，Filter是Servlet API的一部分，而Spring MVC的全局异常处理器（@ControllerAdvice或@RestControllerAdvice）只能捕获Spring MVC控制器中抛出的异常。因此，当Filter抛出异常时，Spring MVC的全局异常处理器无法捕获，导致返回了500错误。

3.2 @RestControllerAdvice未正确扫描

如果GlobalExceptionHandler类所在的包没有被Spring Boot扫描到，它将无法生效。确保GlobalExceptionHandler类所在的包在Spring Boot的扫描路径内。

3.3 Spring Boot的默认错误处理机制

Spring Boot的默认错误处理机制可能会覆盖自定义的异常处理逻辑。可以通过配置application.properties或application.yml文件来调整默认错误处理行为。

4. 解决方案

4.1 在Filter中手动处理异常

由于Filter抛出的异常无法被Spring MVC的全局异常处理器捕获，因此需要在Filter中手动处理异常，将异常信息写入响应中。具体实现如下：

@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)throws IOException, ServletException {HttpServletRequest httpRequest = (HttpServletRequest) request;HttpServletResponse httpResponse = (HttpServletResponse) response;try {// 从域名获取学校信息String serverName = httpRequest.getServerName();String[] domainParts = serverName.split("\\.");if (domainParts.length >= 3) {String subdomain = domainParts[0];// 查询学校IDSchool school = schoolService.getByDomain(subdomain);if (school != null) {// 设置到SchoolContextHolder和请求属性SchoolContextHolder.setSchoolId(school.getId().toString());} else {// 如果找不到学校，抛出异常throw new UnauthorizedAccessException("异常域名");}} else {// 如果不是二级域名，抛出异常throw new UnauthorizedAccessException("异常域名");}chain.doFilter(request, response);} catch (UnauthorizedAccessException ex) {// 手动处理异常，写入响应httpResponse.setStatus(HttpStatus.NOT_FOUND.value());httpResponse.setContentType("application/json;charset=UTF-8");httpResponse.getWriter().write("{\"timestamp\": " + System.currentTimeMillis() + ", \"status\": 404, \"error\": \"Not Found\", \"message\": \"" + ex.getMessage() + "\", \"path\": \"" + httpRequest.getRequestURI() + "\"}");} finally {SchoolContextHolder.clear();}
}

4.2 确保@RestControllerAdvice被正确扫描

确保GlobalExceptionHandler类所在的包在Spring Boot的扫描路径内。例如：

@SpringBootApplication(scanBasePackages = "cn.jbolt")
public class Application {public static void main(String[] args) {SpringApplication.run(Application.class, args);}
}

4.3 调整Spring Boot的默认错误处理机制

可以通过配置application.properties或application.yml文件来调整默认错误处理行为。例如：

server.error.include-stacktrace=never
server.error.include-message=always
server.error.include-binding-errors=always
server.error.include-exception=false

5. 测试验证

5.1 测试用例

使用Postman测试以下两种场景：

  1. 正常请求：请求的域名和路径符合预期，应返回正常响应。

  2. 异常请求：请求的域名不符合预期，应返回404错误。

5.2 测试结果

  • 正常请求：返回正常响应。

  • 异常请求：返回404错误，响应内容如下：

    {"timestamp": 1745483881203,"status": 404,"error": "Not Found","message": "异常域名","path": "/auth/login"
}

6. 注意事项

6.1 异常处理的优先级

如果项目中有多个全局异常处理器，可能会导致异常处理逻辑被覆盖。确保自定义的异常处理逻辑优先级高于其他全局异常处理器。

6.2 日志记录

在全局异常处理器中添加日志记录，方便调试和排查问题。例如：

@ExceptionHandler(UnauthorizedAccessException.class)
public ResponseEntity<String> handleUnauthorizedAccessException(UnauthorizedAccessException ex) {System.out.println("UnauthorizedAccessException-------------------------: " + ex.getMessage());HttpStatus status = ex.getStatus();String message = ex.getMessage();return new ResponseEntity<>(message, status);
}

6.3 响应格式的统一

确保返回的响应格式与前端的要求一致。可以使用统一的错误响应类来封装错误信息，例如：

public class ErrorResponse {private Long timestamp;private int status;private String error;private String message;private String path;// Getters and Setters
}

然后在Filter中返回统一的错误响应：

httpResponse.getWriter().write(new ObjectMapper().writeValueAsString(new ErrorResponse(System.currentTimeMillis(), 404, "Not Found", ex.getMessage(), httpRequest.getRequestURI())));

7. 总结

通过在Filter中手动处理异常，确保返回给前端的响应是正确的404错误，而不是500错误。

相关文章：

  • Android学习总结之Room篇
  • 发送网络请求
  • 《无尽的尽头》今日开播 刘家祎大胆演绎林磊儿的“另一面”
  • RAG（检索增强生成）技术详解与应用实践：从原理到落地
  • 简单几步，开启 Intel VT-x 让电脑“解开CPU封印”
  • 蓝桥杯 20. 压缩变换
  • 数据分析之 商品价格分层之添加价格带
  • 欧姆龙NJ系列PLC通讯
  • vue3-springboot-mysql的docker部署
  • 怎么实现RAG检索相似文档排序：similarities
  • 云蝠智能大模型呼叫：AI驱动的通信服务革新与实践
  • 操作系统---进程同步与互斥
  • 【频谱分析仪与信号分析仪】异同比较
  • Unity后处理全解析：从入门到优化
  • 《Linux程序设计》实验8 线程程序设计
  • vulkanscenegraph显示倾斜模型(6)-帧循环
  • RTS 如何使用流控方式自动实现收发
  • 【每天一个知识点】熵（Entropy）
  • SpringBoot入门实战（项目搭建、配置、功能接口实现等一篇通关）
  • 【KWDB 创作者计划】_上位机知识篇---Github
  • 美银证券前董事总经理胡霁光履新，任摩根士丹利中国区副主席
  • 出发！陈冬、陈中瑞、王杰三名航天员领命出征
  • 独家丨前华金证券宏观首席秦泰加盟华福证券，任研究所副所长
  • 吃饭睡觉打国米，如今的米兰把意大利杯当成宝
  • 杨靖︱“一笔糊涂账”：博马舍与美国革命
  • 2025年超长期特别国债24日首次发行