SpringBoot异常处理机制之自定义404、500错误提示页面

SpringBoot异常处理机制之自定义404、500错误提示页面 - 518篇

news2025/2/25 3:25:01

历史文章（文章累计500+）

《国内最全的Spring Boot系列之一》

《国内最全的Spring Boot系列之二》

《国内最全的Spring Boot系列之三》

《国内最全的Spring Boot系列之四》

《国内最全的Spring Boot系列之五》

《国内最全的Spring Boot系列之六》

《国内最全的Spring Boot系列之七》

Transaction rolled back because it has been marked as - 第512篇

五音不全也浪漫，521清华学霸为爱人写歌 - 第513篇

一文讲清楚SpringBoot项目打包jar后运行报错template might not exist - 第514篇

idea springboot woff/woff2/eot/ttf/svg等小图标不显示的问题 - 第515篇

Noisee AI中文站网页版 AI 音乐生成视频全新登场，快来抢先体验——国内第一个登场的中文站来袭 - 516篇

Spring的SmartLifecycle可以没用过，但没听过就不好了！ - 第517篇

👇AI制作MV - 冰雪奇缘：

以下视频来源于「未来AI视界」公众号

冰雪奇缘

冰雪奇缘2

导读

最近在开发一个AI音乐项目（地址在下面）的时候，由于后端使用的是thymeleaf的模板引擎，在报错的情况下，在页面会直接展示错误信息，这个就很不友好，估计被老板发现了要扣我工资，如果单页面处理，这个就简单，把异常捕捉处理下，但这不是我的风格，我想Spring Boot框架这么强大，一定有通用的异常处理方式。

有粉丝会问：博主，你怎么使用vue进行前后端分离呢？针对这个问题，在后面的一篇文章有关《SpringBoot开发的AI导航站技术架构剖析》我会给出分析和原因。

项目体验地址：

https://suno4.cn/#/?i=8NCBS8_WXTT

前言

在使用Spring Boot开发项目的时候，不管是否是前后端分离的项目，只要是异常信息，就要进行异常的统一处理，尽量不要每个开发人员都处理一遍，如果你的架构师让你自己搞定，那么就打架构师小屁屁吧。

本文主要是针对404和500的错误信息，进行讲解和分析。

一、SpringBoot默认的异常处理机制

SpringBoot 默认已经提供了一套处理异常的机制。一旦程序中出现了异常 SpringBoot 会向 /error 的 url 发送请求。在 SpringBoot 中提供了一个名为 BasicErrorController 的类来处理 /error 请求，然后跳转到默认显示异常的页面来展示异常信息。

1.1 使用模板引擎

在使用 thymeleaf 等模板引擎时，SpringBoot 会自动到 src/main/resources/templates/error/，文件夹下寻找 404.html、500.html 的错误提示页面

错误提示页面的命名规则就是：错误码.html，如 404 是 404.html，500 是 500.html

1.2 没有使用模板引擎

如果没有使用 thymeleaf 等模板引擎时，SpringBoot 会到静态资源文件夹寻找 404.htm、500.html的错误提示页面，命名同上。SpringBoot 中默认的静态资源路径有 4 个，分别是：

· classpath:/METAINF/resources/

· classpath:/resources/

· classpath:/static/

· classpath:/public/

优先级顺序为：META-INF/resources > resources > static > public，以上 4 种路径创建 error 文件夹。

二、SpringBoot异常处理类@ControllerAdvice

@ControllerAdvice就是@Controller增强版，

@ControllerAdvice主要用来处理全局数据，一般搭配

@ExceptionHandler、@ModelAttribute、@InitBinder使用

Controller Advice字面上意思是“控制器通知”，Advice除了“劝告”、“意见”之外，还有“通知”的意思。你可以将@ModelAttribute和@ExceptionHandler标记的方法提取出来，放到一个类里，并将加上@ControllerAdvice，这样，所有的控制器都可以用了：

@ControllerAdvicepublic class GlobalExceptionHandler extends CommonGlobalExceptionHandler {    @ExceptionHandler(RuntimeException.class)    public ModelAndView handleRuntimeException(RuntimeException e, HttpServletRequest request, HttpServletResponse response){ModelAndView modelAndView = new ModelAndView();    modelAndView.setViewName("error/500");    return modelAndView;    }
}

三、我的情况

以上是常规的一个解决思路，当时我是怎么解决的呢？

3.1 使用默认目录下的机制

由于使用了模板引擎的thymeleaf，所以第一种想到的方式就是在templates/下创建error目录，然后创建对应错误编码的.html文件，比如：404.html、500.html：

3.2 失效了？

随着代码越写越多，突然有一天发现错误页面无法正常展示了。

经过我多年的排查，原来是使用了@ControllerAdvice进行了全局异常的处理，导致页面默认的配置失效了。于是忽，我在全局异常类进行了错误页面的配置，如下：

@ExceptionHandler(RuntimeException.class)public ModelAndView handleRuntimeException(RuntimeException e, HttpServletRequest request, HttpServletResponse response){     ModelAndView modelAndView = new ModelAndView();    modelAndView.setViewName("error/error");    return modelAndView;}

当然，这里可以获取到对应的错误码，设置不同的错误页面。

在开发的过程中，会碰到很多的问题，要善于分析和总结问题，这样子自己才能够成长。