> For the complete documentation index, see [llms.txt](https://jack80342.gitbook.io/spring-boot/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://jack80342.gitbook.io/spring-boot/iv.-spring-boot-features/27.-developing-web-applications/27.1.-the-spring-web-mvc-framework/27.1.11.-error-handling.md).

# 27.1.11. 错误处理

Spring Boot默认提供一个`/error`映射用来以合适的方式处理所有的错误，并将它注册为servlet容器中全局的 错误页面。对于机器客户端（相对于浏览器而言，浏览器偏重于人的行为），它会产生一个具有详细错误，HTTP状态，异常信息的JSON响应。对于浏览器客户端，它会产生一个白色标签样式（whitelabel）的错误视图，该视图将以HTML格式显示同样的数据（可以添加一个解析为'error'的View来自定义它）。为了完全替换默认的行为，你可以实现`ErrorController`，并注册一个该类型的bean定义，或简单地添加一个`ErrorAttributes`类型的bean以使用现存的机制，只是替换显示的内容。

**注** `BasicErrorController`可以作为自定义`ErrorController`的基类，如果你想添加对新context type的处理（默认处理`text/html`），这会很有帮助。你只需要继承`BasicErrorController`，添加一个public方法，并注解带有`produces`属性的`@RequestMapping`，然后创建该新类型的bean。

你也可以定义一个注解为`@ControllerAdvice`的类去自定义某个特殊controller或exception类型的JSON文档。如下所示：

```java
@ControllerAdvice(basePackageClasses = AcmeController.class)
public class AcmeControllerAdvice extends ResponseEntityExceptionHandler {

    @ExceptionHandler(YourException.class)
    @ResponseBody
    ResponseEntity<?> handleControllerException(HttpServletRequest request, Throwable ex) {
        HttpStatus status = getStatus(request);
        return new ResponseEntity<>(new CustomErrorType(status.value(), ex.getMessage()), status);
    }

    private HttpStatus getStatus(HttpServletRequest request) {
        Integer statusCode = (Integer) request.getAttribute("javax.servlet.error.status_code");
        if (statusCode == null) {
            return HttpStatus.INTERNAL_SERVER_ERROR;
        }
        return HttpStatus.valueOf(statusCode);
    }

}
```

在以上示例中，如果跟`AcmeController`相同package的某个controller抛出`YourException`，一个`CustomErrorType`类型的POJO的JSON展示将代替`ErrorAttributes`展示。

**自定义错误页面**

如果想为某个给定的状态码展示一个自定义的HTML错误页面，你需要将文件添加到`/error`文件夹下。错误页面既可以是静态HTML（比如，任何静态资源文件夹下添加的），也可以是使用模板构建的，文件名必须是明确的状态码或一系列标签。

例如，映射`404`到一个静态HTML文件，你的目录结构可能如下：

```
src/
 +- main/
     +- java/
     |   + <source code>
     +- resources/
         +- public/
             +- error/
             |   +- 404.html
             +- <other public assets>
```

使用FreeMarker模板映射所有`5xx`错误，你需要如下的目录结构：

```
src/
 +- main/
     +- java/
     |   + <source code>
     +- resources/
         +- templates/
             +- error/
             |   +- 5xx.ftl
             +- <other templates>
```

对于更复杂的映射，你可以添加实现`ErrorViewResolver`接口的beans：

```java
public class MyErrorViewResolver implements ErrorViewResolver {

    @Override
    public ModelAndView resolveErrorView(HttpServletRequest request,
            HttpStatus status, Map<String, Object> model) {
        // Use the request or status to optionally return a ModelAndView
        return ...
    }

}
```

你也可以使用Spring MVC特性，比如[@ExceptionHandler方法](https://docs.spring.io/spring/docs/5.0.4.RELEASE/spring-framework-reference/htmlsingle/#mvc-exceptionhandlers)和[@ControllerAdvice](https://docs.spring.io/spring/docs/5.0.4.RELEASE/spring-framework-reference/htmlsingle/#mvc-ann-controller-advice)，`ErrorController`将处理所有未处理的异常。

**映射Spring MVC以外的错误页面**

对于不使用Spring MVC的应用，你可以通过`ErrorPageRegistrar`接口直接注册`ErrorPages`。该抽象直接工作于底层内嵌servlet容器，即使你没有Spring MVC的`DispatcherServlet`，它们仍旧可以工作。

```java
@Bean
public ErrorPageRegistrar errorPageRegistrar(){
    return new MyErrorPageRegistrar();
}

// ...

private static class MyErrorPageRegistrar implements ErrorPageRegistrar {

    @Override
    public void registerErrorPages(ErrorPageRegistry registry) {
        registry.addErrorPages(new ErrorPage(HttpStatus.BAD_REQUEST, "/400"));
    }

}
```

**注** 如果你注册一个`ErrorPage`，该页面需要被一个`Filter`处理（在一些非Spring web框架中很常见，比如Jersey，Wicket），那么该`Filter`需要明确注册为一个`ERROR`分发器（dispatcher），例如：

```java
@Bean
public FilterRegistrationBean myFilter() {
    FilterRegistrationBean registration = new FilterRegistrationBean();
    registration.setFilter(new MyFilter());
    ...
    registration.setDispatcherTypes(EnumSet.allOf(DispatcherType.class));
    return registration;
}
```

默认的`FilterRegistrationBean`不包含`ERROR` dispatcher类型。

注意：当部署到一个servlet容器时，Spring Boot通过它的错误页面过滤器将带有错误状态的请求转发到恰当的错误页面。request只有在response还没提交时才能转发（forwarded）到正确的错误页面，而WebSphere应用服务器8.0及后续版本默认情况会在servlet方法成功执行后提交response，你需要设置`com.ibm.ws.webcontainer.invokeFlushAfterService`属性为`false`来关闭该行为。