转载

避免滥用http状态码，如何将后端业务错误准确地传递到Restful客户端？Spring Boot和JAX-RS的RFC-7...

在使用JAX-RS，Spring Boot或任何其他技术的RESTful Web服务中,必须使用机器可读且人性化的自定义业务错误代号。

假设您正在编写订单处理系统，客户可能没有资格使用某种付款方式下订单，您想通过Web前端或HTTP API调用的结果向用户反馈这种问题。可以通过查看http规范，并使用代码405：“不允许使用方法”来解决。

听起来完全符合您的需求。它可以在您的测试中工作得很好，并且可以投入生产正常运行一段时间。但是随后，对负载均衡器进行例行更新时会破坏系统。很快，在开发人员和运维人员之间进行了相互指责，最终爆发了一场全面的责任大战。看起来好像是由ops运维人员进行更新引起的问题，但他们声称负载平衡器中没有错误，原因是由于旧版本的安全性问题，必须对其进行更新。

实际上确实应该归咎于开发人员：您误用了具有特定语义的技术代码，以表示完全不同的业务语义-这绝不是一个好主意。在这种情况下，明确使用了可以允许缓存的405代码。

http状态代码（请参阅 rfc-7231 或格式正确的 https://httpstatuses.com ）精确地指定了不同的情况，主要是细粒度的技术问题。特定于应用程序的问题仅限于通用代码 400 Bad Request （以及其他一些 500 Internal Server Error 代码）或状态代码，它们可用于表示客户端或服务器端的一般故障。但是我们需要区分许多情况。我们还能如何将各种问题传达给客户端？

http协议允许几乎在任何响应中不仅在GET请求后具有200 OK状态，还可以包含一个正文（在RFC中称为“实体”）。在这种情况下，大多数系统都会显示自定义html错误页面。如果我们使此主体机器可读，则我们的客户可以做出适当的反应。为每个端点甚至每个应用程序定义一个新的文档类型是一项繁重的工作：您不仅需要编写代码，而且还要编写文档，测试并将其全部传达给客户端等，并且客户端必须使用对于一个请求正是这种格式，对于另一个请求正是这种格式，这太麻烦了。有一个标准会很好-实际上，有一个标准：RFC-7807。

RFC-7807

该标准定义了一种媒体类型application/problem+json（或+xml）以及与其精确语义一起使用的标准字段。这是一个简短的摘要：

  • type：一个URI，用于标识发生了什么类型的问题。理想情况下，它应该是有关此类错误的详细信息的文档的稳定 URL，例如https://api.myshop.example/problems/not-entitled-for-payment-method；但它也可以是 URN ，例如urn:problem-type:not-entitled-for-payment-method。在任何情况下，更改都type被定义为API 的重大更改，因此对于客户而言，使用此方法切换到不同的问题情况是安全的。
  • title：对问题的一般类型的非正式的，人类可读的简短描述，例如You're not entitled to use this payment method。可以在不破坏API的情况下进行更改。
  • status：重复响应状态代码，例如403为Forbidden。由于代理更改了http状态代码，因此服务器抛出的内容和客户端收到的内容可能有所不同。它仅是帮助调试的建议，因此可以在不破坏API的情况下对其进行更改。
  • detail：关于错误原因的易于理解的完整描述，例如Customer 123456 has only GOLD status but needs PLATINUM to be entitled to order the sum of USD 1,234.56 on account.可以在不破坏API的情况下进行更改。
  • instance：用于标识问题具体发生的URI。如果这是URL，则应提供有关此事件的详细信息，例如，指向您的日志https://logging.myshop.example/prod?query=d294b32b-9dda-4292-b51f-35f65b4bf64d-请注意，仅仅因为它是URL，并不意味着所有人都必须可以访问它！如果您甚至不想在Web上提供有关日志记录系统的详细信息，也可以生成一个UUID URN，例如urn:uuid:d294b32b-9dda-4292-b51f-35f65b4bf64d。可以在不破坏API的情况下进行更改。
  • 所有其他字段均为扩展名，即自定义的机器可读字段；例如customer-status或order-sum。扩展也可以是复杂的类型，即列表或包含多个字段的对象，只要它们可以（反）序列化即可。客户可能想将此显示给客户。您可以在不破坏API的情况下添加新扩展名，但是删除扩展名（或更改语义）是对API 的重大更改。

Spring Boot

假设我们有一个REST控制器OrderBoundary（我在这里使用 BCE 术语“边界”）： 

@RestController
@RequestMapping(path = <font>"/orders"</font><font>)
@RequiredArgsConstructor
<b>public</b> <b>class</b> OrderBoundary {
    <b>private</b> <b>final</b> OrderService service;
 
    @PostMapping
    <b>public</b> Shipment order(@RequestParam(</font><font>"article"</font><font>) String article) {
        <b>return</b> service.order(article);
    }
}
</font>

这个OrderService也许抛出UserNotEntitledToOrderOnAccountException错误。

默认情况下，Spring Boot已经提供了一个json错误体，但这是非常技术性的。它包含以下字段：

  • status+ error：例如403和Forbidden
  • message：例如 You're not entitled to use this payment method
  • path：例如 /orders
  • timestamp：例如 2020-01-10T12:00:00.000+0000
  • trace：堆栈跟踪

我们需要通过注释以下内容来指定UserNotEntitledToOrderOnAccountException错误的对应http状态代码和消息：

@ResponseStatus(code = FORBIDDEN,
    reason = <font>"You're not entitled to use this payment method"</font><font>)
<b>public</b> <b>class</b> UserNotEntitledToOrderOnAccountException
  <b>extends</b> RuntimeException {
    ...
}
</font>

注意，没有统一的字段可以区分不同的错误情况，这是我们的主要用例。因此，我们需要采取不同的路线：

1. 手动异常映射

最基本的方法是手动捕获和映射异常，即在我们中，OrderBoundary控制器中我们返回的ResponseEntity中带有两种不同主体类型之一：要么是商品已经运货或出现了问题的详细信息：

<b>public</b> <b>class</b> OrderBoundary {
    @PostMapping
    <b>public</b> ResponseEntity<?> order(@RequestParam(<font>"article"</font><font>) String article) {
        <b>try</b> {
            Shipment shipment = service.order(article);
            <b>return</b> ResponseEntity.ok(shipment);
 
        } <b>catch</b> (UserNotEntitledToOrderOnAccountException e) {
            ProblemDetail detail = <b>new</b> ProblemDetail();
            detail.setType(URI.create(</font><font>"https://api.myshop.example/problems/"</font><font> +
                </font><font>"not-entitled-for-payment-method"</font><font>)); ①
            detail.setTitle(</font><font>"You're not entitled to use this payment method"</font><font>);
            detail.setInstance(URI.create(
                </font><font>"urn:uuid:"</font><font> + UUID.randomUUID())); ②
 
            log.debug(detail.toString(), exception); ③
 
            <b>return</b> ResponseEntity.status(FORBIDDEN).
                contentType(ProblemDetail.JSON_MEDIA_TYPE)
                .body(detail);
        }
    }
}
</font>

①：选择type字段使用固定的URL ，例如对Wiki。

②：选择使用随机UUID URN instance。

③：记录了问题的详细信息和堆栈跟踪，因此我们可以在日志中搜索UUID，instance以查看导致问题的日志上下文中的所有详细信息。

问题细节

ProblemDetail班是微不足道的（使用了Lombok）：

@Data
<b>public</b> <b>class</b> ProblemDetail {
    <b>public</b> <b>static</b> <b>final</b> MediaType JSON_MEDIA_TYPE =
        MediaType.valueOf(<font>"application/problem+json"</font><font>);
 
    <b>private</b> URI type;
    <b>private</b> String title;
    <b>private</b> String detail;
    <b>private</b> Integer status;
    <b>private</b> URI instance;
}
</font>

错误处理器

如果要转换的异常很多，手动映射代码可能会增长很多。通过使用一些约定，我们可以为所有异常将其替换为通用映射。我们可以将还原OrderBoundary为简单形式，而使用异常处理程序控制器建议：

@Slf4j
@ControllerAdvice ①
<b>public</b> <b>class</b> ProblemDetailControllerAdvice {
    @ExceptionHandler(Throwable.<b>class</b>) ②
    <b>public</b> ResponseEntity<?> toProblemDetail(Throwable throwable) {
        ProblemDetail detail = <b>new</b> ProblemDetailBuilder(throwable).build();
 
        log.debug(detail.toString(), throwable); ③
 
        <b>return</b> ResponseEntity.status(detail.getStatus())
            .contentType(ProblemDetail.JSON_MEDIA_TYPE)
            .body(detail);
    }
}
①：使实际的异常处理程序方法可由Spring发现。
②：我们处理所有异常和错误。
③：我们记录详细信息（包括instance）和堆栈跟踪。

有趣的部分在ProblemDetailBuilder里面。

使用的约定是：

  • type：托管于的异常的javadoc的URL https://api.myshop.example/apidocs。这可能不是最稳定的URL，但此演示可以。
  • title：使用简单的类名，将驼峰式大小写转换为空格。
  • detail：异常消息。
  • instance：使用随机UUID URN。
  • status：如果将异常注释为Status使用该注释；否则使用500 Internal Server Error。
@Retention(RUNTIME)
@Target(TYPE)
<b>public</b> @<b>interface</b> Status {
    <b>int</b> value();
}

请注意，您应该非常谨慎地使用约定：它们永远不会令人惊讶。ProblemDetailBuilder是几行代码，但是阅读起来应该很有趣：

@RequiredArgsConstructor
<b>class</b> ProblemDetailBuilder {
    <b>private</b> <b>final</b> Throwable throwable;
 
    ProblemDetail build() {
        ProblemDetail detail = <b>new</b> ProblemDetail();
        detail.setType(buildType());
        detail.setTitle(buildTitle());
        detail.setDetail(buildDetailMessage());
        detail.setStatus(buildStatus());
        detail.setInstance(buildInstance());
        <b>return</b> detail;
    }
 
    <b>private</b> URI buildType() {
        <b>return</b> URI.create(<font>"https://api.myshop.example/apidocs/"</font><font> +
            javadocName(throwable.getClass()) + </font><font>".html"</font><font>);
    }
 
    <b>private</b> <b>static</b> String javadocName(Class<?> type) {
        <b>return</b> type.getName()
            .replace('.', '/') </font><font><i>// the package names are delimited like a path</i></font><font>
            .replace('$', '.'); </font><font><i>// nested classes are delimited with a period</i></font><font>
    }
 
    <b>private</b> String buildTitle() {
        <b>return</b> camelToWords(throwable.getClass().getSimpleName());
    }
 
    <b>private</b> <b>static</b> String camelToWords(String input) {
        <b>return</b> String.join(</font><font>" "</font><font>, input.split(</font><font>"(?=//p{javaUpperCase})"</font><font>));
    }
 
    <b>private</b> String buildDetailMessage() {
        <b>return</b> throwable.getMessage();
    }
 
    <b>private</b> <b>int</b> buildStatus() {
        Status status = throwable.getClass().getAnnotation(Status.<b>class</b>);
        <b>if</b> (status != <b>null</b>) {
            <b>return</b> status.value();
        } <b>else</b> {
            <b>return</b> INTERNAL_SERVER_ERROR.getStatusCode();
        }
    }
 
    <b>private</b> URI buildInstance() {
        <b>return</b> URI.create(</font><font>"urn:uuid:"</font><font> + UUID.randomUUID());
    }
}
</font>

您可以将此错误处理提取到单独的模块中，并且如果您可以与其他团队达成相同的约定，则可以共享它。您甚至可以简单地使用其他人（例如 mine artifact）定义的问题详细信息工件，该工件还允许扩展字段和其他内容。

客户端

我不想在整个域代码中散布技术细节，因此我提取了一个OrderServiceClient类来进行调用并将这些问题详细信息映射回异常。我希望领域代码看起来像这样：

@RequiredArgsConstructor
<b>public</b> <b>class</b> MyApplication {
    <b>private</b> <b>final</b> OrderServiceClient client;
    <b>public</b> OrderStatus handleOrder(String articleId) {
        <b>try</b> {
            Shipment shipment = client.postOrder(articleId);
            <font><i>// store shipment</i></font><font>
            <b>return</b> SHIPPED;
        } <b>catch</b> (UserNotEntitledToOrderOnAccount e) {
            <b>return</b> NOT_ENTITLED_TO_ORDER_ON_ACCOUNT;
        }
    }
}
</font>

有趣部分在OrderServiceClient，在其中手动映射细节错误：

<b>public</b> <b>class</b> OrderServiceClient {
    <b>public</b> Shipment postOrder(String article) {
        MultiValueMap<String, String> form = <b>new</b> LinkedMultiValueMap<>();
        form.add(<font>"article"</font><font>, article);
        RestTemplate template = <b>new</b> RestTemplate();
        <b>try</b> {
            <b>return</b> template.postForObject(BASE_URI + </font><font>"/orders"</font><font>, form, Shipment.<b>class</b>);
        } <b>catch</b> (HttpStatusCodeException e) {
            String json = e.getResponseBodyAsString();
            ProblemDetail problemDetail = MAPPER.readValue(json, ProblemDetail.<b>class</b>);
            log.info(</font><font>"got {}"</font><font>, problemDetail);
            <b>switch</b> (problemDetail.getType().toString()) {
                <b>case</b> </font><font>"https://api.myshop.example/apidocs/com/github/t1/problemdetaildemoapp/"</font><font> +
                        </font><font>"OrderService.UserNotEntitledToOrderOnAccount.html"</font><font>:
                    <b>throw</b> <b>new</b> UserNotEntitledToOrderOnAccount();
                <b>default</b>:
                    log.warn(</font><font>"unknown problem detail type ["</font><font> +
                        ProblemDetail.<b>class</b> + </font><font>"]:/n"</font><font> + json);
                    <b>throw</b> e;
            }
        }
    }
 
    <b>private</b> <b>static</b> <b>final</b> ObjectMapper MAPPER = <b>new</b> ObjectMapper()
        .disable(FAIL_ON_UNKNOWN_PROPERTIES);
}
</font>

下面是响应错误处理，Spring REST客户端上还有一种机制可以使我们对该处理进行概括：

<b>public</b> <b>class</b> OrderServiceClient {
    <b>public</b> Shipment postOrder(String article) {
        MultiValueMap<String, String> form = <b>new</b> LinkedMultiValueMap<>();
        form.add(<font>"article"</font><font>, article);
        RestTemplate template = <b>new</b> RestTemplate();
        template.setErrorHandler(<b>new</b> ProblemDetailErrorHandler()); ①
        <b>return</b> template.postForObject(BASE_URI + </font><font>"/orders"</font><font>, form,
            Shipment.<b>class</b>);
    }
}
①：此行替换了<b>try</b>-<b>catch</b>块。
</font>

ProblemDetailErrorHandler使用了所有约定; 包括一些错误处理。在这种情况下，我们会记录一条警告，然后回退到Spring默认处理方式：

@Slf4j
<b>public</b> <b>class</b> ProblemDetailErrorHandler <b>extends</b> DefaultResponseErrorHandler {
    @Override <b>public</b> <b>void</b> handleError(ClientHttpResponse response) throws IOException {
        <b>if</b> (ProblemDetail.JSON_MEDIA_TYPE.isCompatibleWith(
            response.getHeaders().getContentType())) {
            triggerException(response);
        }
        <b>super</b>.handleError(response);
    }
 
    <b>private</b> <b>void</b> triggerException(ClientHttpResponse response) throws IOException {
        ProblemDetail problemDetail = readProblemDetail(response);
        <b>if</b> (problemDetail != <b>null</b>) {
            log.info(<font>"got {}"</font><font>, problemDetail);
            triggerProblemDetailType(problemDetail.getType().toString());
        }
    }
 
    <b>private</b> ProblemDetail readProblemDetail(ClientHttpResponse response) throws IOException {
        ProblemDetail problemDetail = MAPPER.readValue(response.getBody(), ProblemDetail.<b>class</b>);
        <b>if</b> (problemDetail == <b>null</b>) {
            log.warn(</font><font>"can't deserialize problem detail"</font><font>);
            <b>return</b> <b>null</b>;
        }
        <b>if</b> (problemDetail.getType() == <b>null</b>) {
            log.warn(</font><font>"no problem detail type in:/n"</font><font> + problemDetail);
            <b>return</b> <b>null</b>;
        }
        <b>return</b> problemDetail;
    }
 
    <b>private</b> <b>void</b> triggerProblemDetailType(String type) {
        <b>if</b> (isJavadocUrl(type)) {
            String className = type.substring(36, type.length() - 5)
                .replace('.', '$').replace('/', '.');
            <b>try</b> {
                Class<?> exceptionType = Class.forName(className);
                <b>if</b> (RuntimeException.<b>class</b>.isAssignableFrom(exceptionType)) {
                    Constructor<?> constructor = exceptionType.getDeclaredConstructor();
                    <b>throw</b> (RuntimeException) constructor.newInstance();
                }
                log.warn(</font><font>"problem detail type ["</font><font> + type + </font><font>"] is not a RuntimeException"</font><font>);
            } <b>catch</b> (ReflectiveOperationException e) {
                log.warn(</font><font>"can't instantiate "</font><font> + className, e);
            }
        } <b>else</b> {
            log.warn(</font><font>"unknown problem detail type ["</font><font> + type + </font><font>"]"</font><font>);
        }
    }
 
    <b>private</b> <b>boolean</b> isJavadocUrl(String typeString) {
        <b>return</b> typeString.startsWith(</font><font>"https://api.myshop.example/apidocs/"</font><font>)
            && typeString.endsWith(</font><font>".html"</font><font>);
    }
 
    <b>private</b> <b>static</b> <b>final</b> ObjectMapper MAPPER = <b>new</b> ObjectMapper()
        .disable(FAIL_ON_UNKNOWN_PROPERTIES);
}
</font>

从URL恢复异常类型不是理想的做法，因为它将客户端与服务器紧密地耦合在一起，即，它假定我们在同一包中使用相同的类。对于演示来说已经足够好了，但是要正确地进行演示，您需要一种注册异常或对其进行扫描的方法，例如在 我的库中 ，该方法还允许扩展字段和其他内容。

JAX-RS

如果您不喜欢JAX-RS，则可能要跳到 Summary 。

这部分处理可点击标题见原文。

总结

避免滥用http状态代码；那是个蛇坑。而是生成标准化的并因此可互操作的问题详细信息，这比您想象的要容易。为了不浪费业务逻辑代码，可以在服务器端和客户端使用异常。通过引入一些约定，大多数代码甚至可以通用，并可以在多个应用程序中重用。

此 实现提供了注解@Type，@Title，@Status，@Instance，@Detail，并@Extension为您的自定义异常。它与Spring Boot以及JAX-RS和MicroProfile Rest Client一起使用。Zalando在 问题 库和 Spring集成中 采用了不同的方法。 problem4j也 看起来可用。有一些其他语言的解决方案，例如在GitHub  rfc7807 和 rfc-7807上 。

原文  https://www.jdon.com/53707
正文到此结束
所属分类： Java 编程技术

热门推荐

相关文章

阿里云首购8折
说给你听

本文目录
随机标签
书籍教程
springboot-demo Java入门教程 bootstrap3 CSS Apache基础教程 php ionic 教程 Python mysql教程 eclipse Ubuntu VPS系统配置 AngularJS 教程 MongoDB教程 Struts2教程 Redis教程 Spring教程 Git教程 Jenkins进阶系列 openfire参考指南 Java设计模式 HBase教程 Maven教程 hibernate教程 Docker 教程 memcached教程 Quartz指南 Hive教程 Ant教程 ANTLR教程 SpringCloud java实例教程 springcloud-demo XStream教程 Hazelcast教程 Elastic-Job-Lite 深入浅出MyBatis SVN教程 ibaties教程 rabittmq教程 solr教程 Hadoop教程 WebService CXF学习 JPA教程 ActiveMQ中文指南 java-demo Java内存模型 dubbo教程 python3-demo Linux入门视频教程
近期评论
  1. 1 Spring Cloud Consul实现选举机制
  2. 2 Spring Boot集成ShedLock实现分布式定时任务
  3. 3 利用oss进行数据库和网站图片备份
  4. 4 Spring Cloud Stream实现数据流处理
  5. 5 Python3访问MySQL数据库快速入门Demo
  6. 6 Github开源项目作者可以免费申请 JetBrains 全家桶
  7. 7 Spring Cloud Vault快速入门Demo
  8. 8 Spring Cloud Gateway快速入门Demo
  9. 9 Spring Cloud Contract快速入门Demo
  10. 10 Spring Cloud Consul快速入门Demo
网站信息
  • 文章总数：82,714 篇
  • 文件总数：284,287 个
  • 标签总数：2,393 个
  • 分类总数：85 个
  • 留言数量：2,560 条
  • 在线人数：634 人
  • 运行天数：4,408天
  • 最后更新：2024年11月21日23点
Loading...

其他链接

关于本站

本站定位：个人技术类博客

本站作用：写博客、记日志、闲聊扯淡鼓捣技术。

问题交流

[HBLOG]公众号 HBLOG HBLOG