java - REST最佳实践，用于检索元素的特定子集

Question

好的，所以我们都知道获取所有实体列表的REST方法是HTTP / GET /entities，获取单个实体的最佳方法是HTTP / GET /entities/{entityId}和获取某些实体的最佳方法实体是HTTP / GET /entities/{entityId}?where=condition（*）对吗？

（*）我的意思是/entities?where=condition

但是，当由于延迟而无法选择多个HTTP / GET select ... where id in(id1, id2...)时，需要获取一组特定的实体（等效于SQL entities/{entityId}）时，哪种方法好呢？

特别是我将如何使用RESTEasy做到这一点

Answer 1

尽管您已经找到了解决方案，但由于我不支持接受的答案，因此我将发布答案，原因如下。诚然，这是一个很自以为是的答案，因为HTTP规范允许通过多种方式来实现相似的目的，而REST并不规定某种URI样式，并且为语义解释留出了很大的摆动空间。

关于可能的URI参数的语义，超文本传输​​协议（HTTP）的描述性不是很高。 path和query参数众所周知，但常常忽略header和matrix参数，尽管JAX-RS（最初要求RESTeasy）可以像处理其他参数一样容易。

REST更是一种架构风格，而不是协议。要调用RESTful服务（或API），它必须遵守几个constraints并遵守基础HTTP协议。由于REST是面向资源的，因此使用唯一的资源标识符来调用相应的资源（因此URI）。但是，REST对URI的设计没有任何限制。人们倾向于将一些语义上的意义放入一个良好的URI设计中，尽管对于计算机而言，这只是另外一个字符串。

在您的评论中，您写道：


  我不太喜欢那样。我遇到的大多数API都像我描述的那样工作（也许我使用了错误的API）。


根据我的评论，/entites/{entityId}?where=condition返回一个特定实体的子集，而不是实体的子集。通过将{entityId}指定为URI中的路径参数，您已经将结果集限制为单个实体。如果您打算首先返回与某个实体属性匹配的一组实体，那么为什么还要提供{entityId}？

与矩阵参数f.e相比，查询参数附加到URI的末尾，因此平等地属于每个单个路径段。它们仅属于单个路径段，因此在具有多个路径段的较长URI上传达的语义略有不同。在不包含子资源的简单URI上，矩阵参数和查询参数之间的差异正在逐渐减小，并且它们可以互换使用。但是，对于具有多个路径段的URI，语义可能会有所变化。


  另外我不明白您所说的实体子集是什么意思？


如果您具有ID为user1的用户实体的JSON表示形式，如下所示：

{
    "firstName": "Tim",
    "lastName": "Sample",
    "address": {
        "street": "...",
        "zip": "...",
        "city": "...",
        "country": "..."
    }
}

调用 GET /user/user1?filter=lastName我希望查询通过 { "lastName": "Sample" }过滤后仅返回 address。我希望只返回地址子资源，尽管在这种情况下我会使用 /users/user1/address。诸如 GET /user/user1?lastName=Sample之类的内容可以解释为检查所标识的用户是否具有提供的名称，因此应返回true或false作为响应。如您所见，人类在语义上解释URI或它们的参数，而对于计算机，URI只是包含子字符串，并且他们不在乎参数是作为path，query，matrix还是header参数提供的。他们只是依靠一些预定义的指令，这些指令告诉他们从何处提取所需的信息。

关于可接受的解决方案，我担心的是，使用 POST可以从字面上将任何内容发送到服务器。因此，您需要明确记录需要发送给服务的预期表示形式以及服务器在接收到请求后将执行的行为。此外，使用 POST进行查询时，您将无法缓存响应。后者是 few constraints REST之一。尽管某些缓存框架不会在包含查询参数的URI上缓存响应，但 this link以及 this answer都表明这比现实更像是一个城市传说。

当然，您可以实现服务器端缓存以最小化数据库查找，但是请求仍将到达服务器。使用GET而不是POST时，由于客户端能够缓存答案（如果没有通过特殊的响应头设置阻止），因此请求甚至无法连续尝试到达服务器，因此直接从缓存返回答案，而不是查看状态一遍又一遍。


  但是，当我们需要获取一组特定的实体（相当于一个SQL select）时，这将是一个好方法。当多个HTTP / GET实体/ {entityId}不是一个选择是否由于延迟？


如 an other post中所述，矩阵参数可以在路径段上指定，而不是像查询参数一样在整个URI上指定。这使得它们对于过滤URI的某些部分非常有用。如果您想返回f.e.所有教授着灰色头发的课程，您都可以使用 GET /professors;haircolor=grey/courses之类的东西。您当然可以颠倒结构，并使用类似 /courses/professors?haircolor=grey的语法，这在语法上是完全可以的，但是如果您考虑哪些资源可以更容易地存在而又没有其他资源，并且在更多依赖资源之前使用这些资源，您可能最终会得到前者URI。

因此，对于您的问题可能的解决方案可能是： GET /entity;id={id1};id={id2};...。正如 this answer中所述，在单个资源上使用查询或矩阵参数可能不会有太大区别，但是如果您如果只想返回一组指定用户的所有地址，则可以使用以下内容： GET /users;id={id1};id={id2}/addresses。这允许您在使用HTTP GET时进行响应缓存，还可以在语义上使用资源-子资源语法，其中在引用的资源之前使用一种更有可能存在而另一种则不存在的语法。

由于RESTeasy能够与JAX-RS一起使用，因此可以使用 @MatrixParam批注将矩阵参数轻松地注入到方法参数中。与 @QueryParam或 @PathParam参数一样，底层的JAX-RS框架将尽最大努力尝试 convert the parameter。

@GET
public Response getSomething(@MatrixParam List<String> ids) {
    ...
}

如果无法将参数自动编组到对象，则还可以使用 UriInfo批注注入 @Context对象，然后通过相应的 PathSegment检索矩阵参数，然后对参数进行批注，然后将其编组自己的对象。

@GET
public Response getSomething(@Context UriInfo info) {
    for (PathSegment segment : info.getPathSegments()) {
        MultivaluedMap matrixParameters = segment.getMatrixParameters();
        ...
    }
}

当 PathSegment返回 MultivaluedMap时，相同的键能够返回多个值（作为列表），就像您要插入数据库查询的多个ID一样。 UriInfo在查找路径和查询参数时还提供了 MultivaluedMap。

因此，由您决定使用哪种参数样式，REST不会决定特定的URI设计或语义。但是，建议不要使用 POST来减少将查询发送到服务并获得缓存返回响应的能力所需的文档开销。