避免滥用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

本站部分文章源于互联网,本着传播知识、有益学习和研究的目的进行的转载,为网友免费提供。如有著作权人或出版方提出异议,本站将立即删除。如果您对文章转载有任何疑问请告之我们,以便我们及时纠正。

PS:推荐一个微信公众号: askHarries 或者qq群:474807195,里面会分享一些资深架构师录制的视频录像:有Spring,MyBatis,Netty源码分析,高并发、高性能、分布式、微服务架构的原理,JVM性能优化这些成为架构师必备的知识体系。还能领取免费的学习资源,目前受益良多

转载请注明原文出处:Harries Blog™ » 避免滥用http状态码,如何将后端业务错误准确地传递到Restful客户端?Spring Boot和JAX-RS的RFC-7…

赞 (0)
分享到:更多 ()

评论 0

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址