API分页最佳实践

选项A:带时间戳的键集分页

为了避免您提到的偏移量分页的缺点，您可以使用基于键集的分页。通常，实体有一个时间戳，说明它们的创建或修改时间。此时间戳可用于分页:只需将最后一个元素的时间戳作为下一个请求的查询参数传递。服务器反过来使用时间戳作为筛选条件(例如WHERE modificationDate >= receivedTimestampParameter)

{
    "elements": [
        {"data": "data", "modificationDate": 1512757070}
        {"data": "data", "modificationDate": 1512757071}
        {"data": "data", "modificationDate": 1512757072}
    ],
    "pagination": {
        "lastModificationDate": 1512757072,
        "nextPage": "https://domain.de/api/elements?modifiedSince=1512757072"
    }
}

这样，你就不会漏掉任何元素。这种方法对于许多用例来说应该足够好了。但是，请记住以下几点:

当一个页面的所有元素都具有相同的时间戳时，您可能会陷入无休止的循环。当具有相同时间戳的元素重叠在两个页面时，可以将多个元素多次交付给客户端。

您可以通过增加页面大小和使用精确到毫秒的时间戳来减少这些缺点。

选项B:带有延续令牌的扩展键集分页

要处理上面提到的常规键集分页的缺点，可以向时间戳添加偏移量，并使用所谓的“延续令牌”或“游标”。偏移量是该元素相对于具有相同时间戳的第一个元素的位置。通常，令牌具有类似Timestamp_Offset的格式。它在响应中传递给客户端，并可以提交回服务器以检索下一页。

{
    "elements": [
        {"data": "data", "modificationDate": 1512757070}
        {"data": "data", "modificationDate": 1512757072}
        {"data": "data", "modificationDate": 1512757072}
    ],
    "pagination": {
        "continuationToken": "1512757072_2",
        "nextPage": "https://domain.de/api/elements?continuationToken=1512757072_2"
    }
}

令牌“1512757072_2”指向页面的最后一个元素，并表示“客户端已经获得了时间戳为1512757072的第二个元素”。这样，服务器就知道该往哪里继续。

请注意，您必须处理元素在两个请求之间发生更改的情况。这通常是通过向令牌添加校验和来实现的。这个校验和是对具有此时间戳的所有元素的id进行计算的。因此，我们最终得到了这样的令牌格式:Timestamp_Offset_Checksum。

有关此方法的更多信息，请参阅博客文章“使用延续令牌的Web API分页”。这种方法的一个缺点是实现起来很棘手，因为有许多需要考虑的极端情况。这就是为什么像continuation-token这样的库可以很方便(如果您使用Java/ JVM语言)。免责声明:我是这篇文章的作者和图书馆的合著者。

2017-12-20 12:02:01

我不完全确定您的数据是如何处理的，因此这可能有效，也可能无效，但是您是否考虑过使用时间戳字段进行分页?

当你查询/foos时，你会得到100个结果。你的API应该返回如下内容(假设是JSON，但如果它需要XML，也可以遵循相同的原则):

{
    "data" : [
        {  data item 1 with all relevant fields    },
        {  data item 2   },
        ...
        {  data item 100 }
    ],
    "paging":  {
        "previous":  "http://api.example.com/foo?since=TIMESTAMP1" 
        "next":  "http://api.example.com/foo?since=TIMESTAMP2"
    }

}

只是一个注释，只使用一个时间戳依赖于结果中的隐式“限制”。您可能希望添加显式限制，或者也使用until属性。

时间戳可以使用列表中的最后一个数据项动态确定。这似乎或多或少是Facebook在其Graph API中的分页方式(向下滚动到底部，以我上面给出的格式查看分页链接)。

一个问题可能是，如果您添加了一个数据项，但根据您的描述，听起来它们将被添加到最后(如果没有，请告诉我，我将看看是否可以改进这一点)。

2012-12-16 21:12:53

如果你有分页，你也可以按键对数据排序。为什么不让API客户端在URL中包含之前返回的集合的最后一个元素的键，并在SQL查询中添加一个WHERE子句(或者其他等价的东西，如果您不使用SQL)，以便它只返回那些键大于此值的元素呢?

2012-12-16 21:21:52

可能很难找到最佳实践，因为大多数带有api的系统都不适应这种情况，因为这是一个极端的优势，或者它们通常不会删除记录(Facebook, Twitter)。Facebook实际上表示，由于分页后进行了过滤，每个“页面”可能没有请求的结果数量。 https://developers.facebook.com/blog/post/478/

如果你真的需要适应这种边缘情况，你需要“记住”你停止的地方。jandjorgensen的建议是正确的，但我将使用保证唯一的字段，如主键。您可能需要使用多个字段。

按照Facebook的流程，您可以(也应该)缓存已经请求的页面，如果它们请求已经请求过的页面，则只返回已删除的行。

2012-12-16 21:29:17

再补充一下Kamilk的回答:https://www.stackoverflow.com/a/13905589

这在很大程度上取决于你处理的数据集有多大。小型数据集确实可以有效地进行偏移分页，但大型实时数据集确实需要游标分页。找到了一篇精彩的文章，关于Slack如何随着数据集的增加而进化其api的分页，解释了每个阶段的积极和消极因素:https://slack.engineering/evolving-api-pagination-at-slack-1c1f644f8e12

2018-04-02 17:35:51