释放 API 分页的力量：最佳实践和策略

2025-05-26

释放 API 分页的力量：最佳实践和策略

在现代应用程序开发和数据集成领域，API（应用程序编程接口）是连接各种系统并实现无缝数据交换的支柱。当使用返回大型数据集的 API 时，高效的数据检索对于实现最佳性能和流畅的用户体验至关重要。这时，API 分页就派上用场了。

在本文中，我们将讨论实现 API 分页的最佳实践，确保开发人员能够有效地处理大型数据集并以可管理且高效的方式传递数据。

但在我们进入最佳实践之前，让我们先了解一下什么是 API 分页以及当今使用的标准分页技术。

注意：本文面向已具备 API 知识并具备构建或使用 API 经验的开发者。虽然本文讨论的最佳实践和概念适用于不同的编程语言，但我们将主要使用 Python 作为本文的说明性示例。

了解 API 分页

API 分页是指 API 设计和开发中使用的一种技术，用于以结构化且易于管理的方式检索大型数据集。当 API 端点返回大量数据时，分页可以将数据划分为更小、更易于管理的块或页面。每页包含有限数量的记录或条目。API 使用者或客户端可以请求后续页面来检索更多数据，直到检索到整个数据集。

分页通常涉及使用参数（例如偏移量、限制或基于游标的标记）来控制要检索的数据子集的大小和位置。这些参数决定了起始点以及每页包含的记录数。

通过实现 API 分页，开发人员和消费者可以获得以下优势 -

  • 性能提升：检索和处理较小的数据块可缩短响应时间，并提高 API 调用的整体效率。它最大限度地减少了服务器、网络带宽和客户端应用程序的负载。

  • 减少资源占用：由于分页检索数据时会将数据拆分成更小的子集，因此可以减少服务器和客户端所需的内存、处理能力和带宽。这种高效的资源利用方式可以节省成本并提高可扩展性。

  • 增强的用户体验：分页 API 通过以可管理的份额提供数据，从而提供更佳的用户体验。用户可以逐步浏览数据，访问特定页面或根据需要请求更多数据。这种方法可以实现更流畅的交互、更快的结果渲染，并更轻松地浏览大型数据集。

  • 高效的数据传输：通过分页，仅通过网络传输必要的数据，从而减少传输的数据量并提高网络效率。

  • 可扩展性和灵活性：分页功能允许 API 处理大型数据集，而不会占用过多的系统资源。它为处理不断增长的数据量提供了可扩展的解决方案，并支持跨不同用例和设备进行高效的数据检索。

  • 错误处理：分页功能使错误处理更加易于管理。如果在数据检索过程中发生错误，只需重新加载或处理受影响的页面，而无需重新加载整个数据集。这有助于更有效地隔离和处理错误，确保更顺畅的错误恢复和系统稳定性。

分页 API 的一些常见示例如下 -

  • Twitter、Facebook 和 Instagram 等平台通常采用分页 API 来检索帖子、评论或用户个人资料。
  • 亚马逊、eBay 和 Etsy 等在线市场利用分页 API 来检索产品列表、搜索结果或用户评论。
  • 银行或支付服务提供商通常提供分页 API 来检索交易历史记录、账户报表或客户数据。
  • Indeed 或 LinkedIn Jobs 等求职平台提供分页 API，可根据位置、行业或关键字等各种标准检索职位列表。

常见的 API 分页技术

开发人员可以使用多种常见的 API 分页技术来实现高效的数据检索。以下是一些常用的技术：

1. 偏移和限制分页

此技术涉及使用两个参数：offset和limit。“offset”参数确定数据集中的起点或位置，而“limit”参数指定每页包含的最大记录数。

例如，API 请求可以包含“offset=0”和“limit=10”等参数来检索前 10 条记录。

GET /api/posts?offset=0&limit=10
Enter fullscreen mode Exit fullscreen mode

2.基于游标的分页

基于游标的分页不依赖于数字偏移量，而是使用唯一标识符或令牌来标记数据集中的位置。API 使用者会在后续请求中包含游标值以获取下一页数据。

这种方法可确保在添加新数据或修改现有数据时保持稳定性。游标可以基于各种条件，例如时间戳、主键或记录的编码表示。

例如 -

GET /api/posts?cursor=eyJpZCI6MX0
Enter fullscreen mode Exit fullscreen mode

在上述 API 请求中，游标值eyJpZCI6MX0表示最后获取的记录的标识符。此请求将检索该特定游标之后的下一页帖子。

3.基于页面的分页

基于页面的分页需要使用“page”参数来指定所需的页码。API 使用者请求特定页面的数据，API 会返回相应的页面，通常会附带元数据，例如总页数或总记录数。

这种技术简化了导航，并且通常与其他参数（如“限制”）结合使用来确定每页的记录数。

例如 -

GET /api/posts?page=2&limit=20
Enter fullscreen mode Exit fullscreen mode

在这个 API 请求中，我们请求第二页，其中每页包含 20 个帖子。

4.基于时间的分页

在数据具有时间特征的场景中，基于时间的分页非常有用。它涉及使用与时间相关的参数（例如“start_time”和“end_time”）来指定检索数据的时间范围。

该技术可以按时间顺序或倒序获取数据，从而可以有效地检索近期或历史数据。

例如 -

GET /api/events?start_time=2023-01-01T00:00:00Z&end_time=2023-01-31T23:59:59Z
Enter fullscreen mode Exit fullscreen mode

此处，此请求根据时间戳获取 2023 年 1 月 1 日至 2023 年 1 月 31 日之间发生的事件。

5. 键集分页

键集分页依赖于排序并使用数据集中的唯一属性或键来确定检索下一页的起点。

例如，如果数据按时间戳或标识符排序，API 使用者会将最后看到的时间戳或标识符作为参数，以获取下一组记录。这种技术可确保高效检索后续页面，避免重复或丢失记录。

为了进一步简化这一点，考虑一个 API 请求：

GET /api/products?last_key=XYZ123
Enter fullscreen mode Exit fullscreen mode

这里，XYZ123 代表最后看到的键或标识符。该请求检索键为 XYZ123 的商品集之后的下一组商品。

现在我们已经了解了常见的 API 分页技术，我们已经准备好学习在实现分页 API 时要遵循的最佳实践。

API 分页的最佳实践

在 Python 中实现 API 分页时，有几种最佳实践可供遵循。让我们详细讨论一下：

1. 对分页参数使用通用命名约定：

对分页参数采用一致的命名约定，例如“offset”和“limit”或“page”和“size”。这使得 API 使用者更容易理解和使用您的分页系统。

2. 始终在 API 响应中包含分页元数据：

在 API 响应中提供元数据，以传达有关分页的更多信息。这些信息可以包括记录总数、当前页、页数以及下一页和上一页的链接。这些元数据可帮助 API 使用者更有效地浏览分页数据。

例如，分页 API 的响应应该是这样的 -

{
 "data": [
   {
     "id": 1,
     "title": "Post 1",
     "content": "Lorem ipsum dolor sit amet.",
     "category": "Technology"
   },
   {
     "id": 2,
     "title": "Post 2",
     "content": "Praesent fermentum orci in ipsum.",
     "category": "Sports"
   },
   {
     "id": 3,
     "title": "Post 3",
     "content": "Vestibulum ante ipsum primis in faucibus.",
     "category": "Fashion"
   }
 ],
 "pagination": {
   "total_records": 100,
   "current_page": 1,
   "total_pages": 10,
   "next_page": 2,
   "prev_page": null
 }
}
Enter fullscreen mode Exit fullscreen mode

3.确定合适的页面大小：

选择最佳页面大小，以平衡每页返回的数据量。较小的页面大小可以减少响应负载并提高性能，而较大的页面大小可以减少所需的请求数量。

确定分页 API 的适当页面大小需要考虑各种因素，例如数据的性质、性能考虑和用户体验。

以下是一些帮助您确定最佳页面大小的指南：

  1. 了解数据特征：
    考虑数据集中各个记录的大小和复杂性。如果记录相对较小，您可能能够容纳更大的页面大小，而不会显著影响性能。另一方面，如果记录较大或包含复杂的嵌套结构，建议保持较小的页面大小，以避免响应负载过大。

  2. 考虑网络延迟和带宽：
    考虑典型的网络条件以及 API 消费者可能遇到的潜在延迟或带宽限制。

如果用户使用较慢的网络或带宽有限，较小的页面大小可以帮助减少总体传输时间并提高 API 的响应能力。

  1. 评估性能影响：
    考虑较大页面大小对性能的影响。虽然较大的页面大小可以减少检索完整数据集所需的 API 请求数量，但也可能会增加响应时间并给服务器资源带来额外压力。衡量对性能的影响并监控服务器负载，以在页面大小和性能之间取得平衡。

  2. 考虑用户体验和可用性：
    思考 API 使用者如何与分页数据交互。页面越大，需要浏览的页面数量就越少，从而可以通过减少分页交互次数来提升用户体验。

但是，过大的页面大小可能会使用户难以查找特定记录或高效地浏览数据。在确定最佳页面大小时，请考虑用例和 API 使用者的需求。

  1. 通过分页参数提供灵活性：
    与其强制使用固定的页面大小，不如考虑允许 API 使用者通过参数指定其偏好的页面大小。这种灵活性使使用者能够选择最适合其需求和网络状况的页面大小。

  2. 征求用户反馈：
    如果可能，收集 API 消费者的反馈，以了解他们对页面大小的偏好和要求。

考虑通过用户论坛或支持渠道进行调查或寻求反馈，以了解他们的期望以及他们可能遇到的任何痛点。

4.实现排序和过滤选项：

提供排序和过滤参数，允许 API 使用者指定所需数据的顺序和子集。这增强了灵活性，并使用户能够高效地检索目标结果。

以下是一个使用 Python 在分页 API 中实现排序和过滤选项的示例。在此示例中，我们将使用流行的 Web 框架 Flask 来创建 API：

from flask import Flask, request, jsonify

app = Flask(__name__)

# Dummy data
products = [
    {"id": 1, "name": "Product A", "price": 10.0, "category": "Electronics"},
    {"id": 2, "name": "Product B", "price": 20.0, "category": "Clothing"},
    {"id": 3, "name": "Product C", "price": 15.0, "category": "Electronics"},
    {"id": 4, "name": "Product D", "price": 5.0, "category": "Clothing"},
    # Add more products as needed
]

@app.route('/products', methods=['GET'])
def get_products():
    # Pagination parameters
    page = int(request.args.get('page', 1))
    per_page = int(request.args.get('per_page', 10))

    # Sorting options
    sort_by = request.args.get('sort_by', 'id')
    sort_order = request.args.get('sort_order', 'asc')

    # Filtering options
    category = request.args.get('category')
    min_price = float(request.args.get('min_price', 0))
    max_price = float(request.args.get('max_price', float('inf')))

    # Apply filters
    filtered_products = filter(lambda p: p['price'] >= min_price and p['price'] <= max_price, products)
    if category:
        filtered_products = filter(lambda p: p['category'] == category, filtered_products)

    # Apply sorting
    sorted_products = sorted(filtered_products, key=lambda p: p[sort_by], reverse=sort_order.lower() == 'desc')

    # Paginate the results
    start_index = (page - 1) * per_page
    end_index = start_index + per_page
    paginated_products = sorted_products[start_index:end_index]

    return jsonify(paginated_products)

if __name__ == '__main__':
    app.run(debug=True)
Enter fullscreen mode Exit fullscreen mode

在此示例中，我们定义了一个 /products 端点，它接受各种查询参数，用于排序、筛选和分页。以下是这些参数的使用方法：

  • page：要检索的页码（默认为 1）。
  • per_page：每页的项目数（默认为 10）。
  • sort_by：对产品进行排序的字段（默认为“id”）。
  • sort_order：排序顺序（'asc' 表示升序，'desc' 表示降序，默认为 'asc'）。
  • 类别：过滤产品的类别（可选）。
  • min_price：筛选产品的最低价格（默认为 0）。
  • max_price：筛选产品的最高价格（默认为无穷大）。

下面是一个 cURL 命令示例，用于检索按价格降序排列的第一页产品：

curl -X GET 'http://localhost:5000/products?page=1&per_page=10&sort_by=price&sort_order=desc'
Enter fullscreen mode Exit fullscreen mode

5.保持分页稳定性：

确保分页在请求之间保持稳定一致。新添加或删除的记录不应影响分页期间现有记录的顺序或位置。这可确保用户能够浏览数据而不会遇到意外更改。

为确保 API 分页在请求之间保持稳定和一致，请遵循以下准则：

  1. 使用稳定的排序机制：
    如果您在分页中实现排序，请确保排序机制保持稳定。这意味着，当多条记录的排序字段值相同时，它们的相对顺序在请求之间不应发生变化。例如，如果您按“日期”字段排序，请确保具有相同日期的记录始终以相同的顺序显示。

  2. 避免更改数据顺序：
    除非 API 使用者明确要求，否则在分页期间应避免更改记录的顺序或位置。如果添加新记录或修改现有记录，则不应扰乱分页顺序或导致现有记录意外移动。

  3. 使用唯一且不可变的标识符：
    对分页记录使用唯一且不可变的标识符是一种很好的做法。这确保即使数据发生变化，标识符也能保持不变，从而实现一致的分页。它可以是主键，也可以是与每条记录关联的唯一标识符。

  4. 妥善处理记录删除：
    如果在分页请求之间删除了一条记录，则不应影响分页顺序或导致记录丢失。确保删除记录不会在分页序列中留下空隙。例如，如果删除了记录 X，后续请求不应毫无理由地突然跳转到记录 Y。

  5. **使用确定性分页技术：
    **使用能够提供确定性结果的分页技术。基于游标的分页或键集分页等技术，其分页基于时间戳或唯一标识符等特定属性，能够确保请求之间的稳定性和一致性。

6.处理边缘情况和错误情况：

考虑各种极端情况，例如到达数据集末尾、处理无效或超出范围的页面请求，以及妥善处理错误。提供信息丰富的错误消息和合适的 HTTP 状态代码，以指导 API 使用者处理与分页相关的问题。

以下是处理分页 API 中的边缘情况和错误条件的一些关键注意事项：

  1. 超出范围的页面请求：
    当 API 使用者请求的页面超出可用范围时，务必妥善处理。返回一条信息丰富的错误消息，指出请求的页面超出范围，并在响应中提供相关元数据，以指示最大可用页码。

  2. 无效的分页参数：
    验证 API 使用方提供的分页参数。检查这些值是否在可接受的范围内，并符合您定义的任何特定条件。如果参数无效，则返回相应的错误消息，并详细说明问题。

  3. 处理空结果集：
    如果分页请求导致结果集为空，请在 API 响应中明确指出这一点。在响应中包含元数据，指明记录总数以及未找到指定分页参数的记录。这有助于 API 使用者了解没有更多可用的页面或数据。

  4. 服务器错误和异常处理：
    妥善处理服务器错误和异常。实施错误处理机制来捕获和处理意外错误，确保向 API 使用者返回适当的错误消息和状态码。记录任何相关的错误详细信息，以便进行调试。

  5. 速率限制和节流：
    考虑实施速率限制和节流机制，以防止滥用或过量的 API 请求。强制执行合理的限制，以保护 API 服务器的资源，并确保所有 API 使用者的公平访问。当速率超出限制时，返回特定的错误响应（例如，HTTP 429 请求过多）。

  6. 清晰且信息丰富的错误消息：
    在 API 响应中提供清晰且信息丰富的错误消息，以便在发生错误时为 API 使用者提供指导。请包含错误类型、可能原因以及适用的解决建议的详细信息。这有助于开发者有效地排查和解决问题。

  7. 一致的错误处理方法：
    在整个 API 中建立一致的错误处理方法。遵循标准的 HTTP 状态代码和错误响应格式，以确保 API 使用者的一致性和易理解性。

例如，考虑以下 API -

from flask import Flask, request, jsonify

app = Flask(__name__)

# Dummy data
products = [
    {"id": 1, "name": "Product A", "price": 10.0, "category": "Electronics"},
    {"id": 2, "name": "Product B", "price": 20.0, "category": "Clothing"},
    {"id": 3, "name": "Product C", "price": 15.0, "category": "Electronics"},
    {"id": 4, "name": "Product D", "price": 5.0, "category": "Clothing"},
    # Add more products as needed
]

@app.route('/products', methods=['GET'])
def get_products():
    try:
        # Pagination parameters
        page = int(request.args.get('page', 1))
        per_page = int(request.args.get('per_page', 10))

        # Sorting options
        sort_by = request.args.get('sort_by', 'id')
        sort_order = request.args.get('sort_order', 'asc')

        # Filtering options
        category = request.args.get('category')
        min_price = float(request.args.get('min_price', 0))
        max_price = float(request.args.get('max_price', float('inf')))

        # Validate pagination parameters
        if page < 1 or per_page < 1:
            raise ValueError('Invalid pagination parameters')

        # Apply filters
        filtered_products = filter(lambda p: p['price'] >= min_price and p['price'] <= max_price, products)
        if category:
            filtered_products = filter(lambda p: p['category'] == category, filtered_products)

        # Apply sorting
        sorted_products = sorted(filtered_products, key=lambda p: p[sort_by], reverse=sort_order.lower() == 'desc')

        # Validate page number
        total_products = len(sorted_products)
        total_pages = (total_products + per_page - 1) // per_page
        if page > total_pages:
            raise ValueError('Invalid page number')

        # Paginate the results
        start_index = (page - 1) * per_page
        end_index = start_index + per_page
        paginated_products = sorted_products[start_index:end_index]

        return jsonify({
            'page': page,
            'per_page': per_page,
            'total_pages': total_pages,
            'total_products': total_products,
            'products': paginated_products
        })

    except ValueError as e:
        return jsonify({'error': str(e)}), 400

if __name__ == '__main__':
    app.run(debug=True)
Enter fullscreen mode Exit fullscreen mode

在此示例中，我们将 /products 端点的逻辑包装在 try-except 块中。如果执行过程中发生任何错误，我们会捕获该错误并返回 JSON 响应，其中包含错误消息和相应的状态码（客户端错误为 400）。

我们在此示例中处理的一些错误场景包括：

  • 分页参数无效（page 或 per_page 小于 1）
  • 页码无效（超过总页数）

如果发生任何错误，都会引发异常，并显示描述性错误消息。异常在 except 块中被捕获，然后我们返回一个 JSON 响应，其中包含错误消息和状态码 400（错误请求）。

7.考虑缓存策略：

实施缓存机制来存储分页数据或不经常更改的元数据。缓存可以减少服务器负载并缩短后续请求的响应时间，从而提高性能。

以下是一些您可以考虑的缓存策略：

  1. 页面级缓存：
    缓存每个页面的整个分页响应。这意味着将数据与分页元数据一起缓存。当数据相对静态且不频繁更改时，此策略适用。

  2. 结果集缓存：
    缓存特定查询或查询参数组合的结果集。当相同的查询参数被频繁使用，且结果集在一定时期内保持相对稳定时，此功能非常有用。缓存结果集，并直接将其提供给后续具有相同参数的请求。

  3. 基于时间的缓存：
    根据数据的预期新鲜度设置缓存的过期时间。例如，将分页响应缓存一段时间，例如 5 分钟或 1 小时。缓存期限内的后续请求可以直接从缓存中获取，而无需访问服务器。

  4. 条件缓存：
    使用条件缓存机制，例如 HTTP ETag 或 Last-Modified 标头。如果客户端的缓存版本仍然有效，服务器可以响应 304 Not Modified 状态。这可以减少带宽消耗，并在数据未更改的情况下缩短响应时间。

  5. 反向代理缓存：
    在 API 服务器前端部署一个反向代理服务器（例如 Nginx 或 Varnish）来处理缓存。反向代理可以缓存 API 响应并直接提供服务，而无需将请求转发到后端 API 服务器。这减轻了应用服务器的缓存负担，并提高了性能。

结论

总而言之，实现有效的 API 分页对于提供高效且用户友好的大型数据集访问至关重要。通过遵循最佳实践，例如包含分页元数据、使用稳定的排序机制以及应用适当的缓存策略，开发人员可以优化其分页 API 的性能、可伸缩性和可用性。

通过将这些最佳实践融入到分页 API 的设计和实现中，开发人员可以创建高性能、可扩展且用户友好的界面来访问大型数据集。通过仔细考虑分页技术、错误处理和缓存策略，API 开发人员可以让用户高效地导航和检索所需的数据，最终提升整体 API 体验。

文章来源：https://dev.to/pragativerma18/unlocking-the-power-of-api-pagination-best-practices-and-strategies-4b49
Devto 翻译
PREV
Node.js 从入门到进阶
NEXT
JWT 的危险性及其替代方案