Springboot默认的错误页是如何工作及工作原理你肯定不知道？

2021-10-11 Java网络研发架构师

环境：Springboot2.4.11

环境配置

接下来的演示都是基于如下接口进行。

@RestController
@RequestMApping("/exceptions")
public class ExceptionsController {
    
  @GetMapping("/index")
  public Object index(int a) {
    if (a == 0) {
      throw new BusinessException() ;
    }
    return "exception" ;
  }
    
}

默认错误输出

默认情况下，当请求一个接口发生异常时会有如下两种情况的错误信息提示

基于html

基于JSON

上面两个示例通过请求的Accept请求头设置希望接受的数据类型，得到不同的响应数据类型。

标准web错误页配置

在标准的JAVA web项目中我们一般是在web.xml文件中进行错误页的配置，如下：

<error-page>
  <location>/error</location>
</error-page>

如上配置后，如发生了异常以后容器会自动地跳转到错误页面。

Spring实现原理

在Springboot中没有web.xml，并且Servlet API也没有提供相应的API进行错误页的配置。那么在Springboot中又是如何实现错误页的配置呢？

Springboot内置了应用服务，如Tomcat，Undertow，Jetty，默认是Tomcat。那接下来看下基于默认的Tomcat容器错误页是如何进行配置的。

Servlet Web服务自动配置

@EnableConfigurationProperties(ServerProperties.class)
@Import({ServletWebServerFactoryAutoConfiguration.BeanPostProcessorsRegistrar.class, 
         ServletWebServerFactoryConfiguration.EmbeddedTomcat.class,...})
public class ServletWebServerFactoryAutoConfiguration {
  @Configuration(proxyBeanMethods = false)
  @ConditionalOnClass({ Servlet.class, Tomcat.class, UpgradeProtocol.class })
  @ConditionalOnMissingBean(value = ServletWebServerFactory.class, search = SearchStrategy.CURRENT)
  static class EmbeddedTomcat {

    // 这里主要就是配置Web 容器服务，如这里使用的Tomcat
    // 注意该类实现了ErrorPageRegistry ，那么也就是说该类可以用来注册错误页的
    @Bean
    TomcatServletWebServerFactory tomcatServletWebServerFactory(
      ObjectProvider<TomcatConnectorCustomizer> connectorCustomizers,
      ObjectProvider<TomcatContextCustomizer> contextCustomizers,
      ObjectProvider<TomcatProtocolHandlerCustomizer<?>> protocolHandlerCustomizers) {
      TomcatServletWebServerFactory factory = new TomcatServletWebServerFactory();
      factory.getTomcatConnectorCustomizers().addAll(connectorCustomizers.orderedStream().collect(Collectors.toList()));
      factory.getTomcatContextCustomizers().addAll(contextCustomizers.orderedStream().collect(Collectors.toList()));
      factory.getTomcatProtocolHandlerCustomizers().addAll(protocolHandlerCustomizers.orderedStream().collect(Collectors.toList()));
      return factory;
    }

  }
}

在@Import中只列出了两个比较重要的
BeanPostProcessorsRegistrar与EmbeddedTomcat

BeanPostProcessorsRegistrar注册了两个BeanPostProcessor处理器

public static class BeanPostProcessorsRegistrar implements ImportBeanDefinitionRegistrar, BeanFactoryAware {
  public void registerBeanDefinitions(AnnotationMetadata importingClassMetadata, BeanDefinitionRegistry registry) {
    if (this.beanFactory == null) {
      return;
    }
    registerSyntheticBeanIfMissing(registry, "webServerFactoryCustomizerBeanPostProcessor", WebServerFactoryCustomizerBeanPostProcessor.class, WebServerFactoryCustomizerBeanPostProcessor::new);
    registerSyntheticBeanIfMissing(registry, "errorPageRegistrarBeanPostProcessor", ErrorPageRegistrarBeanPostProcessor.class, ErrorPageRegistrarBeanPostProcessor::new);
  }
}

通过名称也能知道
WebServerFactoryCustomizerBeanPostProcessor用来处理Tomcat相关的自定义信息；
ErrorPageRegistrarBeanPostProcessor 这个就是重点了，这个就是用来配置我们的自定义错误页面的。

public class ErrorPageRegistrarBeanPostProcessor implements BeanPostProcessor, BeanFactoryAware {
  @Override
  public Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
    // 这里判断了当前的bean对象是否是ErrorPageRegistry的实例
    // 当前类既然是BeanPostProcessor实例，同时上面注册了一个TomcatServletWebServerFactory Bean实例
    // 那么在实例化TomcatServletWebServerFactory时一定是会调用该BeanPostProcessor处理器的
    if (bean instanceof ErrorPageRegistry) {
      postProcessBeforeInitialization((ErrorPageRegistry) bean);
    }
    return bean;
  }
  // 注册错误页面
  private void postProcessBeforeInitialization(ErrorPageRegistry registry) {
    for (ErrorPageRegistrar registrar : getRegistrars()) {
      registrar.registerErrorPages(registry);
    }
  }
  private Collection<ErrorPageRegistrar> getRegistrars() {
    if (this.registrars == null) {
      // Look up does not include the parent context
      // 从当前上下文中（比包括父上下文）查找ErrorPageRegistrar Bean对象
      this.registrars = new ArrayList<>(this.beanFactory.getBeansOfType(ErrorPageRegistrar.class, false, false).values());
      this.registrars.sort(AnnotationAwareOrderComparator.INSTANCE);
      this.registrars = Collections.unmodifiableList(this.registrars);
    }
    return this.registrars;
  }
}

注册错误页面

在上一步中知道了错误页的注册入口是在一个
ErrorPageRegistrarBeanPostProcessor Bean后处理器中进行注册的，接下来继续深入查看这个错误页是如何被注册的。

接着上一步在
ErrorPageRegistrarBeanPostProcessor中查找ErrorPageRegistrar类型的Bean对象。在另外一个自动配置中（ErrorMvcAutoConfiguration）有注册ErrorPageRegistrar Bean对象

@AutoConfigureBefore(WebMvcAutoConfiguration.class)
@EnableConfigurationProperties({ ServerProperties.class, WebMvcProperties.class })
public class ErrorMvcAutoConfiguration {
  
  // 该类是ErrorPageRegistrar子类，那么在注册错误页的时候注册的就是该类中生成的错误页信息
  static class ErrorPageCustomizer implements ErrorPageRegistrar, Ordered {
    private final ServerProperties properties;
    private final DispatcherServletPath dispatcherServletPath;
    protected ErrorPageCustomizer(ServerProperties properties, DispatcherServletPath dispatcherServletPath) {
      this.properties = properties;
      this.dispatcherServletPath = dispatcherServletPath;
    }
    @Override
    public void registerErrorPages(ErrorPageRegistry errorPageRegistry) {
      // 错误页的地址可以在配置文件中自定义server.error.path进行配置，默认：/error
      ErrorPage errorPage = new ErrorPage(this.dispatcherServletPath.getRelativePath(this.properties.getError().getPath()));
      errorPageRegistry.addErrorPages(errorPage);
    }
    @Override
    public int getOrder() {
      return 0;
    }
  }

}

关键代码

//  errorPageRegistry对象的实例是TomcatServletWebServerFactory 
errorPageRegistry.addErrorPages(errorPage);

TomcatServletWebServerFactory中注册错误页信息，该类的父类（AbstractConfigurableWebServerFactory）方法中有添加错误也的方法

public abstract class AbstractConfigurableWebServerFactory {
  private Set<ErrorPage> errorPages = new LinkedHashSet<>();
  public void addErrorPages(ErrorPage... errorPages) {
    this.errorPages.addAll(Arrays.asList(errorPages));
  }
}

这个错误页的注册到Tomcat容器中又是如何实现的呢？

Tomcat中注册错误页

接下来看看这个错误页是如何与Tomcat关联在一起的。

Spring容器最核心的方法是refresh方法

public abstract class AbstractApplicationContext {
  public void refresh() {
    // ...
    // Initialize other special beans in specific context subclasses.
    onRefresh();
    // ...
  }
}

执行onRefresh方法

public class ServletWebServerApplicationContext extends GenericWebApplicationContext {
  protected void onRefresh() {
    super.onRefresh();
    try {
      // 创建Tomcat服务
      createWebServer();
    } catch (Throwable ex) {
      throw new ApplicationContextException("Unable to start web server", ex);
    }
  }
  private void createWebServer() {
    // ...
    // 返回应用于创建嵌入的Web服务器的ServletWebServerFactory。默认情况下，此方法在上下文本身中搜索合适的bean。
    // 在上面ServletWebServerFactoryAutoConfiguration自动配置中，已经自动的根据当前的环境创建了TomcatServletWebServerFactory对象
    ServletWebServerFactory factory = getWebServerFactory();
    // 获取WebServer实例， factory = TomcatServletWebServerFactory
    this.webServer = factory.getWebServer(getSelfInitializer());
    // ...
  }
}

调用
TomcatServletWebServerFactory#getWebServer方法

public class TomcatServletWebServerFactory extends AbstractServletWebServerFactory {
  public WebServer getWebServer(ServletContextInitializer... initializers) {
    // ...
    Tomcat tomcat = new Tomcat();
    // ...
    // 预处理上下文
    prepareContext(tomcat.getHost(), initializers);
    return getTomcatWebServer(tomcat);
  }
  protected void prepareContext(Host host, ServletContextInitializer[] initializers) {
    // ...
    // 配置上下文
    configureContext(context, initializersToUse);
	}
  protected void configureContext(Context context, ServletContextInitializer[] initializers) {
    TomcatStarter starter = new TomcatStarter(initializers);
    // ...
    // 在这里就将错误的页面注册到了tomcat容器中
    for (ErrorPage errorPage : getErrorPages()) {
      org.Apache.tomcat.util.descriptor.web.ErrorPage tomcatErrorPage = new org.apache.tomcat.util.descriptor.web.ErrorPage();
      tomcatErrorPage.setLocation(errorPage.getPath());
      tomcatErrorPage.setErrorCode(errorPage.getStatusCode());
      tomcatErrorPage.setExceptionType(errorPage.getExceptionName());
      context.addErrorPage(tomcatErrorPage);
    }
    // ...
  }
}

到此你就知道了一个错误的页是如何在Springboot中被注册的。到目前为止我们看到的注册到tomcat容器中的错误页都是个地址，比如：默认是/error。那这个默认的/error又是怎么提供的接口呢？

默认错误页

在Springboot中默认有个自动配置的错误页，在上面有一个代码片段你应该注意到了

@AutoConfigureBefore(WebMvcAutoConfiguration.class)
@EnableConfigurationProperties({ ServerProperties.class, WebMvcProperties.class })
public class ErrorMvcAutoConfiguration {
  @Bean
  @ConditionalOnMissingBean(value = ErrorAttributes.class, search = SearchStrategy.CURRENT)
  public DefaultErrorAttributes errorAttributes() {
    return new DefaultErrorAttributes();
  }
  @Bean
  @ConditionalOnMissingBean(value = ErrorController.class, search = SearchStrategy.CURRENT)
  public BasicErrorController basicErrorController(ErrorAttributes errorAttributes, ObjectProvider<ErrorViewResolver> errorViewResolvers) {
    return new BasicErrorController(errorAttributes, this.serverProperties.getError(), errorViewResolvers.orderedStream().collect(Collectors.toList()));
  }
}

查看这个Controller

// 默认的错误页地址是/error
@Controller
@RequestMapping("${server.error.path:${error.path:/error}}")
public class BasicErrorController extends AbstractErrorController {
  
  @RequestMapping(produces = MediaType.TEXT_HTML_VALUE)
  public ModelAndView errorHtml(HttpServletRequest request, HttpServletResponse response) {
    HttpStatus status = getStatus(request);
    Map<String, Object> model = Collections.unmodifiableMap(getErrorAttributes(request, getErrorAttributeOptions(request, MediaType.TEXT_HTML)));
    response.setStatus(status.value());
    ModelAndView modelAndView = resolveErrorView(request, response, status, model);
    return (modelAndView != null) ? modelAndView : new ModelAndView("error", model);
  }

  @RequestMapping
  public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) {
    HttpStatus status = getStatus(request);
    if (status == HttpStatus.NO_CONTENT) {
      return new ResponseEntity<>(status);
    }
    Map<String, Object> body = getErrorAttributes(request, getErrorAttributeOptions(request, MediaType.ALL));
    return new ResponseEntity<>(body, status);
  }

}

这里有两个方法，分别处理了不同的Accept请求头。到此你是否真正地明白了Springboot中的错误处理的工作原理呢？

完毕！！！