RESTful Web API设计的一个领域(经常被忽视)是如何报告与业务或应用程序有关的错误和问题。 首先要想到HTTP状态代码的正确用法,尽管它非常方便,但通常它的信息量还不够。 让我们以400错误请求为例。 是的,它清楚地表明请求是有问题的,但是究竟出了什么问题呢?
RESTful的体系结构风格并不决定在这种情况下应该做什么,因此每个人都在发明自己的风格,约定和规范。 它可能像将错误消息包含到响应中一样简单,也可能像复制/粘贴长堆栈跟踪记录一样是短视的(对于Java或.NET,仅举几例)。 并不缺乏想法,但是幸运的是,我们至少有一些以RFC 7807形式提供的指南:HTTP API的问题详细信息 。 尽管它不是官方规范,而是草案(仍然),但它概述了有关当前问题的良好通用原则,这就是我们在本文中要讨论的内容。
简而言之, RFC 7807:HTTP API的问题详细信息仅提出了错误或问题表示形式( JSON或XML格式),其中可能至少包括以下详细信息:
- type –标识问题类型的URI参考
- 标题 –问题类型的简短易读摘要
- status – HTTP状态代码
- 详细信息 –针对此问题的发生的易于理解的解释
- 实例 –标识问题特定发生的URI参考
更重要的是,问题类型定义可以使用其他成员扩展问题详细信息对象,从而为上述成员做出贡献。 如您所见,从实现角度看,它看起来非常简单。 更好的是,感谢
Zalando ,我们已经有了
RFC 7807:HTTP API实现的问题详细信息 对于Java (和 特别是Spring Web )。 所以……让我们尝试一下!
我们将使用最新的技术堆栈, Spring Boot和Apache CXF ,流行的Web服务框架和JAX-RS 2.1实现来构建我们虚构的People Management Web API。 为了简单起见,仅公开了两个端点:注册和按人员标识符查找。
撇开开发现实世界服务时可能遇到的大量问题和业务约束,即使使用此简单的API,也可能会出错。 我们要解决的第一个问题是,如果您要寻找的人尚未注册怎么办? 看起来很适合404 Not Found ,对吗? 确实,让我们从第一个问题PersonNotFoundProblem开始 !
public class PersonNotFoundProblem extends AbstractThrowableProblem {
private static final long serialVersionUID = 7662154827584418806L;
private static final URI TYPE = URI.create("http://localhost:21020/problems/person-not-found");
public PersonNotFoundProblem(final String id, final URI instance) {
super(TYPE, "Person is not found", Status.NOT_FOUND,
"Person with identifier '" + id + "' is not found", instance,
null, Map.of("id", id));
}
}
它非常类似于典型的Java异常,并且确实是一个,因为AbstractThrowableProblem是RuntimeException的子类。 这样,我们可以从JAX-RS API中抛出它。
@Produces({ MediaType.APPLICATION_JSON, "application/problem+json" })
@GET
@Path("{id}")
public Person findById(@PathParam("id") String id) {
return service
.findById(id)
.orElseThrow(() -> new PersonNotFoundProblem(id, uriInfo.getRequestUri()));
}
如果我们运行服务器并尝试获取提供任何标识符的人员,则将返回问题详细信息响应(因为未预先填充数据集),例如:
$ curl "http://localhost:21020/api/people/1" -H "Accept: */*"
HTTP/1.1 404
Content-Type: application/problem+json
{
"type" : "http://localhost:21020/problems/person-not-found",
"title" : "Person is not found",
"status" : 404,
"detail" : "Person with identifier '1' is not found",
"instance" : "http://localhost:21020/api/people/1",
"id" : "1"
}
请注意应用程序/问题+ json媒体类型的用法以及响应中包含的其他属性ID 。 尽管有许多可以改进的地方,但是可以说它比仅裸露的404 (或由EntityNotFoundException引起的500 )要好。 另外,如果需要进一步的说明,可以参考此类问题背后的文档部分(在我们的情况下为http:// localhost:21020 / problems / person-not-found )。
因此,在例外之后设计问题只是一种选择。 您可能经常(出于非常正当的理由)会避免将业务逻辑与无关的细节耦合在一起。 在这种情况下,返回问题详细信息作为JAX-RS资源的响应有效负载是完全有效的。 例如,注册过程可能会引发NonUniqueEmailException,因此我们的Web API层可以将其转换为适当的问题详细信息。
@Consumes(MediaType.APPLICATION_JSON)
@Produces({ MediaType.APPLICATION_JSON, "application/problem+json" })
@POST
public Response register(@Valid final CreatePerson payload) {
try {
final Person person = service.register(payload.getEmail(),
payload.getFirstName(), payload.getLastName());
return Response
.created(uriInfo.getRequestUriBuilder().path(person.getId()).build())
.entity(person)
.build();
} catch (final NonUniqueEmailException ex) {
return Response
.status(Response.Status.BAD_REQUEST)
.type("application/problem+json")
.entity(Problem
.builder()
.withType(URI.create("http://localhost:21020/problems/non-unique-email"))
.withInstance(uriInfo.getRequestUri())
.withStatus(Status.BAD_REQUEST)
.withTitle("The email address is not unique")
.withDetail(ex.getMessage())
.with("email", payload.getEmail())
.build())
.build();
}
}
要触发此问题,只需运行服务器实例并尝试两次注册同一个人即可,就像我们在下面所做的那样。
$ curl -X POST "http://localhost:21020/api/people" \
-H "Accept: */*" -H "Content-Type: application/json" \
-d '{"email":"john@smith.com", "firstName":"John", "lastName": "Smith"}'
HTTP/1.1 400
Content-Type: application/problem+json
{
"type" : "http://localhost:21020/problems/non-unique-email",
"title" : "The email address is not unique",
"status" : 400,
"detail" : "The email 'john@smith.com' is not unique and is already registered",
"instance" : "http://localhost:21020/api/people",
"email" : "john@smith.com"
}
太好了,因此我们的最后一个示例有些复杂,但同时可能是最现实的示例。 我们的Web API在很大程度上依赖Bean验证 ,以确保API使用者提供的输入有效。 我们如何将验证错误表示为问题的详细信息? 最直接的方法是提供专用的ExceptionMapper提供程序,它是JAX-RS规范的一部分。 让我们介绍一个。
@Provider
public class ValidationExceptionMapper implements ExceptionMapper<ValidationException> {
@Context private UriInfo uriInfo;
@Override
public Response toResponse(final ValidationException ex) {
if (ex instanceof ConstraintViolationException) {
final ConstraintViolationException constraint = (ConstraintViolationException) ex;
final ThrowableProblem problem = Problem
.builder()
.withType(URI.create("http://localhost:21020/problems/invalid-parameters"))
.withTitle("One or more request parameters are not valid")
.withStatus(Status.BAD_REQUEST)
.withInstance(uriInfo.getRequestUri())
.with("invalid-parameters", constraint
.getConstraintViolations()
.stream()
.map(this::buildViolation)
.collect(Collectors.toList()))
.build();
return Response
.status(Response.Status.BAD_REQUEST)
.type("application/problem+json")
.entity(problem)
.build();
}
return Response
.status(Response.Status.INTERNAL_SERVER_ERROR)
.type("application/problem+json")
.entity(Problem
.builder()
.withTitle("The server is not able to process the request")
.withType(URI.create("http://localhost:21020/problems/server-error"))
.withInstance(uriInfo.getRequestUri())
.withStatus(Status.INTERNAL_SERVER_ERROR)
.withDetail(ex.getMessage())
.build())
.build();
}
protected Map<?, ?> buildViolation(ConstraintViolation<?> violation) {
return Map.of(
"bean", violation.getRootBeanClass().getName(),
"property", violation.getPropertyPath().toString(),
"reason", violation.getMessage(),
"value", Objects.requireNonNullElse(violation.getInvalidValue(), "null")
);
}
}
上面的代码片段区分了两种问题: ConstraintViolationException指示无效输入并映射到400 Bad Request ,而泛型ValidationException指示服务器端问题并映射到500 Internal Server Error 。 我们仅提取有关违规的基本详细信息,但是即使这样做,也可以大大改进错误报告功能。
$ curl -X POST "http://localhost:21020/api/people" \
-H "Accept: */*" -H "Content-Type: application/json" \
-d '{"email":"john.smith", "firstName":"John"}' -i
HTTP/1.1 400
Content-Type: application/problem+json
{
"type" : "http://localhost:21020/problems/invalid-parameters",
"title" : "One or more request parameters are not valid",
"status" : 400,
"instance" : "http://localhost:21020/api/people",
"invalid-parameters" : [
{
"reason" : "must not be blank",
"value" : "null",
"bean" : "com.example.problem.resource.PeopleResource",
"property" : "register.payload.lastName"
},
{
"reason" : "must be a well-formed email address",
"value" : "john.smith",
"bean" : "com.example.problem.resource.PeopleResource",
"property" : "register.payload.email"
}
]
}
这次捆绑到invalid-parameters成员中的附加信息非常冗长:我们分别知道类( PeopleResource ),方法( register ),方法的参数( 有效负载 )和属性( lastName和email )(所有这些都从属性路径)。
有意义的错误报告是现代RESTful Web API的基础之一。 通常这并不容易,但绝对值得付出努力。 消费者(通常只是其他开发人员)应该对哪里出了问题以及如何处理有一个清晰的了解。 RFC 7807:HTTP API的问题详细信息是朝正确方向迈出的一步, 问题和问题弹簧网络之类的库在这里为您提供支持,请充分利用它们。
完整的源代码可在Github上找到 。
翻译自: https://www.javacodegeeks.com/2019/05/http-status-code-enough-tackling-web-apis-error-reporting.html