Update 27.1.8 Error Handling.md

Author: qibaoguang

IV. Spring Boot features/27.1.8 Error Handling.md

@@ -1,27 +1,98 @@
 ### 27.1.8 错误处理
 
-Spring Boot默认提供一个/error映射用来以合适的方式处理所有的错误，并且它在servlet容器中注册了一个全局的
-错误页面。对于机器客户端（相对于浏览器而言，浏览器偏重于人的行为），它会产生一个具有详细错误，HTTP状态，异常信息的JSON响应。对于浏览器客户端，它会产生一个白色标签样式（whitelabel）的错误视图，该视图将以HTML格式显示同样的数据（可以添加一个解析为erro的View来自定义它）。为了完全替换默认的行为，你可以实现ErrorController，并注册一个该类型的bean定义，或简单地添加一个ErrorAttributes类型的bean以使用现存的机制，只是替换显示的内容。
+Spring Boot默认提供一个`/error`映射用来以合适的方式处理所有的错误，并且它注册为servlet容器中全局的
+错误页面。对于机器客户端（相对于浏览器而言，浏览器偏重于人的行为），它会产生一个具有详细错误，HTTP状态，异常信息的JSON响应。对于浏览器客户端，它会产生一个白色标签样式（whitelabel）的错误视图，该视图将以HTML格式显示同样的数据（可以添加一个解析为'error'的View来自定义它）。为了完全替换默认的行为，你可以实现`ErrorController`，并注册一个该类型的bean定义，或简单地添加一个`ErrorAttributes`类型的bean以使用现存的机制，只是替换显示的内容。
 
-如果在某些条件下需要比较多的错误页面，内嵌的servlet容器提供了一个统一的Java DSL（领域特定语言）来自定义错误处理。
-示例：
+**注** `BasicErrorController`可以作为自定义`ErrorController`的基类，如果你想添加对新context type的处理（默认处理`text/html`），这会很有帮助。你只需要继承`BasicErrorController`，添加一个public方法，并注解带有`produces`属性的`@RequestMapping`，然后创建该新类型的bean。
+
+你也可以定义一个`@ControllerAdvice`去自定义某个特殊controller或exception类型的JSON文档：
+```java
+@ControllerAdvice(basePackageClasses = FooController.class)
+public class FooControllerAdvice 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);
+    }
+
+}
+```
+在以上示例中，如果跟`FooController`相同package的某个controller抛出`YourException`，一个`CustomerErrorType`类型的POJO的json展示将代替`ErrorAttributes`展示。
+
+**自定义错误页面**
+
+如果想为某个给定的状态码展示一个自定义的HTML错误页面，你需要将文件添加到`/error`文件夹下。错误页面既可以是静态HTML（比如，任何静态资源文件夹下添加的），也可以是使用模板构建的，文件名必须是明确的状态码或一系列标签。
+
+例如，映射`404`到一个静态HTML文件，你的目录结构可能如下：
+```properties
+src/
+ +- main/
+     +- java/
+     |   + <source code>
+     +- resources/
+         +- public/
+             +- error/
+             |   +- 404.html
+             +- <other public assets>
+```
+使用FreeMarker模板映射所有`5xx`错误，你需要如下的目录结构：
+```properties
+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方法](http://docs.spring.io/spring/docs/4.3.3.RELEASE/spring-framework-reference/htmlsingle/#mvc-exceptionhandlers)和[@ControllerAdvice](http://docs.spring.io/spring/docs/4.3.3.RELEASE/spring-framework-reference/htmlsingle/#mvc-ann-controller-advice)，`ErrorController`将处理所有未处理的异常。
+
+**映射Spring MVC以外的错误页面**
+
+对于不使用Spring MVC的应用，你可以通过`ErrorPageRegistrar`接口直接注册`ErrorPages`。该抽象直接工作于底层内嵌servlet容器，即使你没有Spring MVC的`DispatcherServlet`，它们仍旧可以工作。
 ```java
 @Bean
-public EmbeddedServletContainerCustomizer containerCustomizer(){
-    return new MyCustomizer();
+public ErrorPageRegistrar errorPageRegistrar(){
+    return new MyErrorPageRegistrar();
 }
 
 // ...
-private static class MyCustomizer implements EmbeddedServletContainerCustomizer {
+
+private static class MyErrorPageRegistrar implements ErrorPageRegistrar {
+
     @Override
-    public void customize(ConfigurableEmbeddedServletContainer container) {
-        container.addErrorPages(new ErrorPage(HttpStatus.BAD_REQUEST, "/400"));
+    public void registerErrorPages(ErrorPageRegistry registry) {
+        registry.addErrorPages(new ErrorPage(HttpStatus.BAD_REQUEST, "/400"));
     }
+
 }
 ```
-你也可以使用常规的Spring MVC特性来处理错误，比如[@ExceptionHandler方法](http://docs.spring.io/spring/docs/4.1.4.RELEASE/spring-framework-reference/htmlsingle/#mvc-exceptionhandlers)和[@ControllerAdvice](http://docs.spring.io/spring/docs/4.1.4.RELEASE/spring-framework-reference/htmlsingle/#mvc-ann-controller-advice)。ErrorController将会捡起任何没有处理的异常。
-
-N.B. 如果你为一个路径注册一个ErrorPage，最终被一个过滤器（Filter）处理（对于一些非Spring web框架，像Jersey和Wicket这很常见），然后过滤器需要显式注册为一个ERROR分发器（dispatcher）。
+注.如果你注册一个`ErrorPage`，该页面需要被一个`Filter`处理（在一些非Spring web框架中很常见，比如Jersey，Wicket），那么该`Filter`需要明确注册为一个`ERROR`分发器（dispatcher），例如：
 ```java
 @Bean
 public FilterRegistrationBean myFilter() {
@@ -32,4 +103,8 @@ public FilterRegistrationBean myFilter() {
     return registration;
 }
 ```
-**注**：默认的FilterRegistrationBean没有包含ERROR分发器类型。
+（默认的`FilterRegistrationBean`不包含`ERROR` dispatcher类型）。
+
+**WebSphere应用服务器的错误处理**
+
+当部署到一个servlet容器时，Spring Boot通过它的错误页面过滤器将带有错误状态的请求转发到恰当的错误页面。request只有在response还没提交时才能转发（forwarded）到正确的错误页面，而WebSphere应用服务器8.0及后续版本默认情况会在servlet方法成功执行后提交response，你需要设置`com.ibm.ws.webcontainer.invokeFlushAfterService`属性为`false`来关闭该行为。