通过Spring Boot来自定义404 Not Found等错误的显示方式

2 年 ago
清, 宇
8 minutes

总结

    Web アプリケーション全体で発生する 404 Not Found などのエラーについて、Spring Boot での表示内容をカスタマイズする

这次的环境

    • Spring Boot 2.2.0

 

    • Spring Boot Thymeleaf Starter 2.2.0

 

    Thymeleaf 3.0.11

默认情况下，将返回Whitelabel Error Page或JSON。

当通过Web浏览器访问时发生错误，默认情况下会显示一个名为“白标签错误页面”的页面。

Whitelabel Error Page

This application has no explicit mapping for /error, so you are seeing this as a fallback.

Wed Nov 06 18:38:41 JST 2019
There was an unexpected error (type=Internal Server Error, status=500).
This is a sample error.

Spring Boot参考文档

对于浏览器客户端，有一个“白标签”错误视图，它以 HTML 格式呈现相同的数据（如需自定义，请添加一个视图以解析错误信息）。

另外，对于不是常规网络浏览器而是机器性质的客户端，如curl命令等，将生成包含错误、HTTP状态和异常消息详细信息的JSON响应。

{"timestamp":"2019-11-06T09:30:58.493+0000","status":500,"error":"Internal Server Error","message":"This is a sample error.","path":"/sample/"}

Spring Boot 参考文档

对于机器客户端，它会生成一个包括错误详情、HTTP状态以及异常信息的JSON响应。

参考: Spring Boot中白标签错误页与JSON响应 – Qiita

默认提供的 /error 映射（error.html）

即使没有进行特殊设置，Spring Boot也会以适当的方式处理所有错误并提供”/error”映射。这被注册为Servlet容器的”全局”错误页面。

Spring Boot参考文档

默认情况下，Spring Boot提供了一个/error映射来合理处理所有错误，并且它会在Servlet容器中注册为“全局”错误页面。

在Thymeleaf中，如果视图名称为/error，那么可以将位于src/main/resources/templates/error.html的文件作为错误页面处理。

错误.html

只需准备以下Thymeleaf所需的HTML模板文件即可。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>/error</title>
</head>
<body>
  <div th:text="'timestamp: ' + ${timestamp}"></div>
  <div th:text="'status: ' + ${status}"></div>
  <div th:text="'error: ' + ${error}"></div>
  <div th:text="'exception: ' + ${exception}"></div>
  <div th:text="'message: ' + ${message}"></div>
  <div th:text="'errors: ' + ${errors}"></div>
  <div th:text="'trace: ' + ${trace}"></div>
  <div th:text="'path: ' + ${path}"></div>
</body>
</html>

可以在error.html中输出的属性

在错误页面中，可以输出一些信息。
“/error” 映射是由 Spring Boot 的 DefaultErrorAttributes 类实现的，在 API 参考文档中列出了可以输出的项目。

默认的错误属性（Spring Boot Docs 2.2.0.RELEASE API）

当可能时，默认实现错误属性。提供以下属性：
– 时间戳 – 提取错误的时间
– 状态 – 状态码
– 错误 – 错误原因
– 异常 – 根异常的类名（如果已配置）
– 消息 – 异常消息
– 错误 – 来自BindingResult异常的任何ObjectErrors
– 追踪 – 异常的堆栈跟踪
– 路径 – 异常发生时的URL路径

错误页面的示例输出

如果出现500内部服务器错误的情况。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>/error</title>
</head>
<body>
  <div>timestamp: Wed Nov 06 18:26:31 JST 2019</div>
  <div>status: 500</div>
  <div>error: Internal Server Error</div>
  <div>exception: null</div>
  <div>message: This is a sample error.</div>
  <div>errors: null</div>
  <div>trace: null</div>
  <div>path: /sample/</div>
</body>
</html>

如果遇到 404 Not Found 的情况。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>/error</title>
</head>
<body>
  <div>timestamp: Wed Nov 06 18:25:40 JST 2019</div>
  <div>status: 404</div>
  <div>error: Not Found</div>
  <div>exception: null</div>
  <div>message: No message available</div>
  <div>errors: null</div>
  <div>trace: null</div>
  <div>path: /aaa</div>
</body>
</html>

如果访问 /error，状态码将变成 999。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>/error</title>
</head>
<body>
  <div>timestamp: Wed Nov 06 18:24:30 JST 2019</div>
  <div>status: 999</div>
  <div>error: None</div>
  <div>exception: null</div>
  <div>message: No message available</div>
  <div>errors: null</div>
  <div>trace: null</div>
  <div>path: null</div>
</body>
</html>

可以使用 /error/400.html 或者 /error/4xx.html 来取代 error.html。

Spring Boot的DefaultErrorViewResolver类负责处理这部分逻辑。

spring-boot/DefaultErrorViewResolver.java在v2.2.0.RELEASE版本上的土星星球的链接是spring-projects/spring-boot的一个仓库。

  static {
    Map<Series, String> views = new EnumMap<>(Series.class);
    views.put(Series.CLIENT_ERROR, "4xx");
    views.put(Series.SERVER_ERROR, "5xx");
    SERIES_VIEWS = Collections.unmodifiableMap(views);
  }

  @Override
  public ModelAndView resolveErrorView(HttpServletRequest request, HttpStatus status, Map<String, Object> model) {
    ModelAndView modelAndView = resolve(String.valueOf(status.value()), model);
    if (modelAndView == null && SERIES_VIEWS.containsKey(status.series())) {
      modelAndView = resolve(SERIES_VIEWS.get(status.series()), model);
    }
    return modelAndView;
  }

  private ModelAndView resolve(String viewName, Map<String, Object> model) {
    String errorViewName = "error/" + viewName;
    TemplateAvailabilityProvider provider = this.templateAvailabilityProviders.getProvider(errorViewName,
        this.applicationContext);
    if (provider != null) {
      return new ModelAndView(errorViewName, model);
    }
    return resolveResource(errorViewName, model);
  }

默认的错误视图解析器 (Spring Boot 文档 2.2.0.RELEASE API)

默认的ErrorViewResolver实现，尝试使用众所周知的约定解析错误视图。将使用状态码和状态系列在”/error”下搜索模板和静态资源。
例如，HTTP 404将按照以下顺序搜索：

・’//error/404.’
・’//error/404.html’
・’//error/4xx.’
・’//error/4xx.html’

可以在 server.error.path 中更改 /error。

错误页面的显示由Spring Boot的BasicErrorController处理。

spring-boot/BasicErrorController.java 在 v2.2.0.RELEASE 版本的 spring-projects/spring-boot 的 GitHub 上。

@Controller
@RequestMapping("${server.error.path:${error.path:/error}}")
public class BasicErrorController extends AbstractErrorController {

可以通过在 application.properties 文件中进行设置来更改 server.error.path 的设定值。参考：常用应用属性。

默认的/error映射的问题

/错误 您即使在服务器上放置了与错误映射对应的error.html文件，也会在/error页面上遇到999错误，而且机械化的客户端比如curl等，仍然会遇到意外的JSON响应问题。

以下提供一种解决这些问题的方法。

如何自定义错误处理？

替换默认错误处理的方法包括实现ErrorController接口，或者继续使用现有的BasicErrorController等现有处理方法并实现ErrorAttributes接口以替换内容。

《Spring Boot参考文档》

要完全替代默认行为，你可以实现ErrorController并注册一个该类型的bean定义，或者添加一个ErrorAttributes类型的bean来使用现有机制但替换内容。

使用ErrorController自定义错误处理。

通过实现ErrorController来自定义错误处理的方法在这里进行演示。

准备一个实现ErrorController接口的类。

准备实现ErrorController接口的类，以确定错误页面的视图并设置要显示的信息。

import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.web.servlet.error.ErrorController;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.servlet.ModelAndView;

import javax.servlet.RequestDispatcher;
import javax.servlet.http.HttpServletRequest;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;

/**
 * Web アプリケーション全体のエラーコントローラー。
 * エラー情報を HTML や JSON で出力する。
 * ErrorController インターフェースの実装クラス。
 */
@Controller
@RequestMapping("${server.error.path:${error.path:/error}}") // エラーページへのマッピング
public class MyErrorController implements ErrorController {

  /**
   * エラーページのパス。
   */
  @Value("${server.error.path:${error.path:/error}}")
  private String errorPath;

  /**
   * エラーページのパスを返す。
   *
   * @return エラーページのパス
   */
  @Override
  public String getErrorPath() {
    return errorPath;
  }

  /**
   * HTML レスポンス用の ModelAndView オブジェクトを返す。
   *
   * @param request リクエスト情報
   * @return HTML レスポンス用の ModelAndView オブジェクト
   */
  @RequestMapping(produces = MediaType.TEXT_HTML_VALUE)
  public ModelAndView myErrorHtml(HttpServletRequest request) {

    // HTTP ステータスを決める
    // ここでは 404 以外は全部 500 にする
    Object statusCode = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
    HttpStatus status = HttpStatus.INTERNAL_SERVER_ERROR;
    if (statusCode != null && statusCode.toString().equals("404")) {
      status = HttpStatus.NOT_FOUND;
    }

    // 出力したい情報をセットする
    ModelAndView mav = new ModelAndView();
    mav.setStatus(status); // HTTP ステータスをセットする
    mav.setViewName("error"); // error.html
    mav.addObject("timestamp", new Date());
    mav.addObject("status", status.value());
    mav.addObject("path", request.getAttribute(RequestDispatcher.ERROR_REQUEST_URI));

    return mav;
  }

  /**
   * JSON レスポンス用の ResponseEntity オブジェクトを返す。
   *
   * @param request リクエスト情報
   * @return JSON レスポンス用の ResponseEntity オブジェクト
   */
  @RequestMapping
  public ResponseEntity<Map<String, Object>> myErrorJson(HttpServletRequest request) {

    // HTTP ステータスを決める
    // ここでは 404 以外は全部 500 にする
    Object statusCode = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
    HttpStatus status = HttpStatus.INTERNAL_SERVER_ERROR;
    if (statusCode != null && statusCode.toString().equals("404")) {
      status = HttpStatus.NOT_FOUND;
    }

    // 出力したい情報をセットする
    Map<String, Object> body = new HashMap<String, Object>();
    body.put("timestamp", new Date());
    body.put("status", status.value());
    body.put("path", request.getAttribute(RequestDispatcher.ERROR_REQUEST_URI));

    return new ResponseEntity<>(body, status);
  }
}

参考：

    • ErrorController (Spring Boot Docs 2.2.0.RELEASE API)

 

    • spring-boot/BasicErrorController.java at v2.2.0.RELEASE · spring-projects/spring-boot · GitHub

 

    Spring Boot エラーページの最低限のカスタマイズ (ErrorController インターフェースの実装) – Qiita

准备一个HTML模板作为视图。

准备一个针对视图名称的HTML模板文件error.html.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>/error</title>
</head>
<body>
  <div th:text="'timestamp: ' + ${timestamp}"></div>
  <div th:text="'status: ' + ${status}"></div>
  <div th:text="'path: ' + ${path}"></div>
</body>
</html>

现在，当出现404 Not Found等错误时，这些实现类将负责处理。

使用ErrorAttributes和ErrorViewResolver来自定义错误处理。

在这里，我们通过实现ErrorAttributes和ErrorViewResolver来定制错误处理的方式。

准备一个实现ErrorAttributes接口的类

首先，准备一个实现ErrorAttributes接口的类，用于返回设置为响应JSON或ModelAndView的信息。

import org.springframework.boot.web.servlet.error.DefaultErrorAttributes;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestAttributes;
import org.springframework.web.context.request.WebRequest;

import java.util.Date;
import java.util.HashMap;
import java.util.Map;

/**
 * ログに記録したりユーザーに提示するエラー情報へのアクセスを提供する。
 * ErrorAttributes インターフェースを実装するため、DefaultErrorAttributes クラスを継承している。
 */
@Component // DIコンテナに登録する
public class MyErrorAttributes extends DefaultErrorAttributes {

  /**
   * エラー情報を返す。
   * エラー情報は、エラーページ ModelAndView のモデルとして使用するか
   * または @ResponseBody の JSON データとして使用する。
   * @param webRequest リクエスト情報
   * @param includeStackTrace スタックトレースを含める必要がある場合は true
   * @return エラー情報
   */
  @Override
  public Map<String, Object> getErrorAttributes(WebRequest webRequest, boolean includeStackTrace) {

    // エラー情報の Map オブジェクト
    // ここにレスポンス JSON やエラーページに必要な情報を追加していく
    Map<String, Object> attr = new HashMap<String, Object>();

    // timestamp
    attr.put("timestamp", new Date());

    // status
    Object status = webRequest.getAttribute("javax.servlet.error.status_code", RequestAttributes.SCOPE_REQUEST);
    if (status == null) {
      status = 999; // ここでは 999 にしておく
    }
    attr.put("status", status);

    // path
    Object path = webRequest.getAttribute("javax.servlet.error.request_uri", RequestAttributes.SCOPE_REQUEST);
    if (path != null) {
      attr.put("path", path);
    }

    // 独自のエラーメッセージを追加する
    attr.put("myErrorMessage", status);

    return attr;
  }
}

可以参考：

    • ErrorAttributes (Spring Boot Docs 2.2.0.RELEASE API)

 

    spring-boot/spring-boot-project/spring-boot/src/main/java/org/springframework/boot/web/servlet/error at v2.2.0.RELEASE · spring-projects/spring-boot · GitHub

准备一个实现ErrorViewResolver接口的类

接下来，我们需要准备一个ErrorViewResolver接口的实现类，以确定错误页面的视图并设置要显示的信息。

import org.springframework.boot.autoconfigure.web.servlet.error.ErrorViewResolver;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.ModelAndView;

import javax.servlet.http.HttpServletRequest;
import java.util.Map;

/**
 * エラービューを決める bean クラス。
 */
@Component // DIコンテナに登録する
public class MyErrorViewResolver implements ErrorViewResolver {

  public MyErrorViewResolver() {
    System.out.println("MyErrorViewResolver created");
  }

  /**
   * エラービューを決定する。
   *
   * @param request リクエスト情報
   * @param status  エラーの HTTP ステータス
   * @param model   ビューで使うために提示されたモデル
   * @return 決定した ModelAndView または null
   */
  @Override
  public ModelAndView resolveErrorView(
    HttpServletRequest request,
    HttpStatus status,
    Map<String, Object> model) {

    // モデルとビューの情報を構築
    ModelAndView mav = new ModelAndView();

    // MyErrorAttributes#getErrorAttributes の戻り値をセット
    mav.addAllObjects(model);

    // ビュー名を指定
    mav.setViewName("myerror"); // resources/templates/myerror.html

    // ステータスに応じて処理
    if (status == HttpStatus.NOT_FOUND) {
      // 404 Not Found
      mav.setStatus(HttpStatus.NOT_FOUND);
      mav.addObject("myErrorMessage", "404 Not Found");
    } else {
      // 404 以外は全部 500 にする
      mav.setStatus(HttpStatus.INTERNAL_SERVER_ERROR);
      mav.addObject("myErrorMessage", "500 Internal Server Error");
    }

    return mav;
  }
}

参考：

    • ErrorViewResolver (Spring Boot Docs 2.2.0.RELEASE API)

 

    spring-boot/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/web/servlet/error at v2.2.0.RELEASE · spring-projects/spring-boot · GitHub

准备一个可以作为视图的HTML模板。

为视图名称准备一个与之匹配的HTML模板文件myerror.html。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>/myerror</title>
</head>
<body>
  <div th:text="'myErrorMessage: ' + ${myErrorMessage}"></div>
  <div th:text="'timestamp: ' + ${timestamp}"></div>
  <div th:text="'status: ' + ${status}"></div>
  <div th:text="'path: ' + ${path}"></div>
</body>
</html>

這樣，當出現404 Not Found等錯誤時，這些實現類將處理該錯誤。

请提供参考资料。

    • Spring Boot Reference Documentation – The “Spring Web MVC Framework” – Error Handling

 

    • SpringBootを使うときに最低限やっておきたいセキュリティ対策 – Qiita

 

    Spring Boot で Boot した後に作る Web アプリケーション基盤/spring-boot-application-infrastructure – Speaker Deck
✖
广告
将在 10 秒后关闭
bannerAds