如何设计Restful API的分页？

最新推荐文章于 2025-10-29 09:27:23 发布
原创 最新推荐文章于 2025-10-29 09:27:23 发布 · 9k 阅读 · 2 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

本文探讨了在设计RESTful API时如何实现分页。建议使用URL查询参数，如?page=1和?size=100来指定页数和每页大小，因为这种方式更利于URL分享和传统A标签兼容。在数据格式方面，比较了基于page、offset和cursor的方法，认为对于大型数据集，cursor方式更有效，但page-based在多数情况下是折衷选择。在回复方式上，推荐通过JSON返回分页信息，包括总记录数、当前页数和每页大小，而GitHub则将分页信息放在HTTP Header的link字段中。

需要考虑的问题:

  • 请求方式
  • 回复方式

请求方式

可考虑的传递通道:

  • url query, /foo?page=1
  • url path, /foo/page/1
  • http request json body
  • http header

比较:

  • page不是resource，所以不应该设计在url path中
  • 需要考虑到url复制分享和传统a标签兼容问题的情况，这里还不谈及SEO，所以应该来说url query还是最优选择

数据格式:

  • 基于page, [page:4, per_page:50]
  • 基于offset, [offset:200, limit: 50]
  • 基于cursor, [cursor: timestamp, limit: 50]

page和offset比较简单，但是在large datasets查询时会效率比较低，没有索引，所以才会有cursor方式，但是考虑到github, zoom，同时兼顾client的友好性，采用page-based还是比较折中的选择。

  • ?page=2&size=100: 指定第几页，以及每页的记录数
  • ?offset=100&limit=10: 指定返回记录的数量
  • ?sort=name+,group-: 多属性排序

回复方式

  • json
  • http header

github比较特殊，采用了将pagination信息已link方式放在了http header中，http body就是比较纯粹的array，所以github翻页也只有上一页，下一页。

一般来说，用json更多一些，回复内容包括:

  • total: 总数
  • page: 当前页数 (1-based)
  • size: 当前每页数量
  • items: 具体记录数组
Flask restful分页接口实现
qq_41891186的博客
05-24 955
flask分页接口,restful风格接口
Restful API优雅原则统一规范
热门推荐
曾经“等你生日那天”都遥远得像未来，如今却可欢愉的挥手说“下个十年见”
10-14 10万+
本部分预留作业，后续总结后分享。
前后端分离开发，RESTful 接口应该这样设计
yang202924111010的博客
03-22 725
前言 REST（Representational State Transfer）架构风格是一种世界观，把信息提升为架构中的一等公民。通过 REST 可以实现系统的高性能、可伸缩、通用性、简单性、可修改性和可扩展等特性。这篇文章解释了主要的 HTTP 操作，对 HTTP 响应码进行描述，并列举相关开发库和框架。此外，本文还提供了额外的资源，对每个主题进行了更深入的探讨。 简介 REST 架构风格...
什么是RESTful API？它的设计原则是什么？
最新发布
破损的天堂鸟博客
10-29 582
同时，以 OpenAPI 为核心的工具链、以 API 网关为中心的架构模式，以及以自动化和零信任为导向的安全策略，正在共同塑造下一代 API 生态系统。最终，提供清晰的文档、稳定的性能、强大的安全保障和一致的设计，共同构成了卓越的开发者体验（DX），这已成为衡量 API 成功与否的关键指标。RESTful API 作为一种成熟且强大的架构风格，其核心设计原则——客户端-服务器分离、无状态、可缓存、统一接口、分层系统——在今天依然具有强大的生命力，为构建可伸缩、可维护的分布式系统提供了坚实的理论基础。
RestfulQueries：一种在REST API上添加过滤，分页，排序，搜索的简便方法
02-04
宁静查询 通过支持分页，过滤，选择，排序和搜索来开发真正的静态API。 该项目可帮助您轻松地将这些功能添加到REST Controller中，而无需开发自定义解决方案。 该项目目前仅与Spring Data MongoDB应用程序兼容。 这里有一篇博客文章，我其中逐步描述了该库的实现。 入门 对于基于Maven的项目，将以下内容添加到pom.xml文件中。 可从Maven Central存储库中获得此​​依赖关系。 < dependency> < groupId>com.github.apavlidi</ groupId> < artifactId>restfulQ
Spring| RestfulAIP分页
YvesHe的专栏
06-20 414
首相想到的是在返回的数据中增加数据直接返回JSON数据就好,后面考虑做到返回数据精简不包括这些数据分页URL数据,那么我么就想到了在响应头HttpResponse中设置header的方式来设置实现,考虑到项目中使用了SpringMVC模块,首先想到的是利用Spring的拦截器来设置: 一顿操作猛如虎,然而不能生效,后面不得不是使用实现Spring中ResponseBodyAdvice接口来实现 ...
RESTful API 设计最佳实践
coder 的历程
06-13 1298
背景 目前互联网上充斥着大量的关于RESTful API（为了方便，以后API和RESTful API 一个意思）如何设计的文章，然而却没有一个”万能“的设计标准：如何鉴权？API格式如何？你的API是否应该加入版本信息？当你开始写一个app的时候，特别是后端模型部分已经写完的时候，你不得不殚精竭虑的设计和实现自己app的public API部分。因为一旦发布，对外发布的API将会很难改变。 ...
Flask如何实现RESTful API设计？
HunterLawrence的博客
04-20 536
Python的Flask框架因其轻便、灵活和易于扩展的特性，成为了开发RESTful API的优选工具。通过遵循RESTful原则和设计良好的端点，你可以创建一个强大且易于使用的API，为客户端应用程序提供数据和服务。在开发过程中，记得考虑安全性、性能和可用性等因素，以确保你的API能够满足用户的需求并应对未来的挑战。要创建一个新的待办事项，你可以发送一个包含JSON有效负载的POST请求到相同的URL。：客户端和服务器之间的通信必须是无状态的，即每个请求必须包含理解该请求所必需的所有信息。
【高频考点精讲】前端GraphQL实践：如何替代RESTful API设计？
全栈老李的博客
05-18 957
🧑‍🏫：全栈老李📅：2025 年 5 月🧑‍💻：前端初学者、进阶开发者🚀：本文由全栈老李原创，转载请注明出处。最近在给团队做技术分享时，发现不少前端同学对GraphQL还停留在"听说过"的阶段。作为一个从RESTful时代走过来的老司机，今天全栈老李就带大家看看GraphQL这把"瑞士军刀"在前端开发中的实战应用。
RESTful API的设计与实现
jun778895的博客
07-14 1520
RESTful API的设计与实现随着互联网的快速发展，Web应用程序的需求也日益增长。为了满足这些需求，开发人员需要一种标准的方式来设计和实现Web服务。REST（Representational State Transfer）作为一种轻量级的、遵循HTTP协议的Web服务架构风格，逐渐成为Web服务设计的首选。RESTful API是REST风格的具体实现，它提供了一组用于交互和操作资源的接口。本文将详细探讨RESTful API的设计与实现。
如何在PHP中实现RESTful API开发？
破损的天堂鸟博客
01-09 1225
无论是使用Swagger还是Apiary，编写PHP RESTful API文档的步骤大致相同，主要包括安装必要的工具、编写API注解或文档、生成规范文件、部署文档以及测试和验证API。
聊聊RESTful - 接口设计篇（一）
就浩这口
10-04 1万+
在我的上一篇文章科普篇中为大家介绍了REST的起源与REST成熟度模型。同时我也指出网上有大量介绍RESTful接口设计的文章，如果我们不理解真正的REST，那么单纯的接口设计的讨论会让我们对REST产生误解。那么在我们了解了什么是真正的REST之后，再来讨论接口设计，就是学以致用
Yii2——restful API 数据分页
weixin_30551947的博客
09-30 1524
本文链接：https://www.cnblogs.com/alanabc/p/9729026.html Yii 的文档，如果没有完整的看完，真的不好发挥它的威力。 先看看这一节：Yii 2.0 权威指南 - RESTFUL WEB 服务 - 快速入门 这里写了逐页列出，有的时候还真的忽略了，毕竟示例里就几个数据，哪看得出来分页。 设置分页 用一个Controller写的话就是： <?p...
Restful—分页和过滤
beichen0518的博客
05-05 4771
Restful—分页和过滤 # settings.py 中 # 配置restful api 返回结果 REST_FRAMEWORK = { # 分页 'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination', 'PAGE_SIZE': 8, # 设置搜索 想要实现...
Restful API 的设计规范
爱是与世界平行
09-07 837
一、URI 1.1 URI规范 1.2 资源集合 vs 单个资源 1.3 避免层级过深的URI 1.4 对Conposite资源的访问 二、Request 2.1 HTTP方法 2.2 安全性和幂等性 2.3 复杂查询 2.4 Bookmarker 2.5 Format 2.6 Content Negotiation 三、Response 分页res...
restful api 自我见解的一个分页小插件
二手程序员
12-11 2081
简单分页只需要两个参数：页码，每页多少条 在restful参数设计中，分页有自己独特的参数：page与per_page，不可以改名字 给controller加上这样的一个类 package com.heroku.controller; import java.util.Properties; import org.springframework.context.annot
API 设计——分页
山茶树和葡萄树
01-08 1644
分页方案 页大小、页号 起始位置offset、条数size ☑ 浏览方式 初始翻页 指定位置(收藏、输入) 无限滚动加载 改变每页列表项 请求方式 总条数，HEAD，响应头，X-Record-Count，调用一次前端本地存储 条目列表， GET 频繁更新的数据，总条数与条目列表合一 参考：《AngularJS 深度剖析与最佳实践》 ...
RESTFul风格接口如何设计
m0_63949203的博客
10-02 454
RESTFul风格接口如何设计
RESTful 接口设计
花铛
04-28 658
RESTful 是一种接口设计风格，充分利用了 HTTP 方法的语义。一句话概括：看 URI 就知道要什么资源，看 http method 就知道要干什么，看 http status code 就知道结果如何。
如何设计RESTful风格的API路由？
08-05
设计符合RESTful风格的API路由结构需要遵循一系列核心原则和最佳实践，以确保API的可扩展性、可维护性和一致性。以下是一些关键的设计要点和建议： ### 资源命名 - **使用名词而非动词**：RESTful API的设计应基于资源，而不是操作。因此，API的URL应该使用名词来表示资源，而不是动词。例如，使用`/users`而不是`/getUsers`。 - **复数形式**：资源名称通常使用复数形式，以表示集合。例如，`/users`而不是`/user`。 ### 路由结构 - **层级结构**：通过嵌套资源来表示层次关系。例如，`/users/{user_id}/orders`表示某个用户的订单列表。 - **HTTP方法**：不同的HTTP方法对应不同的操作。GET用于获取资源，POST用于创建资源，PUT用于更新资源，DELETE用于删除资源。 ### 版本控制 - **URL路径版本**：在URL中包含版本号，例如`/api/v1/users`。这种方法直观且易于配置，但会导致URL冗长。 - **查询参数版本**：通过查询参数指定版本，例如`/api/users?version=1`。这种方法保持URL简洁，但不够明显，且可能影响缓存。 - **请求头版本**：通过请求头指定版本，例如`X-API-Version: 1`。这种方法符合REST规范且灵活扩展，但学习成本较高。 ### 错误处理 - **标准HTTP状态码**：使用标准的HTTP状态码来表示请求的结果。例如，200表示成功，404表示资源未找到，500表示服务器内部错误。 - **详细的错误信息**：在响应体中提供详细的错误信息，帮助客户端理解和处理错误。 ### 分页、排序和过滤 - **分页**：对于返回大量数据的请求，使用分页机制。例如，`/users?page=2&per_page=10`。 - **排序**：允许客户端指定排序方式。例如，`/users?sort=name,asc`。 - **过滤**：提供过滤功能，以便客户端可以根据特定条件查询数据。例如，`/users?filter=age>30`。 ### 安全性 - **认证和授权**：确保API的安全性，使用OAuth、JWT等机制进行认证和授权。 - **速率限制**：防止滥用，设置速率限制，例如每分钟最多请求次数。 ### 文档和测试 - **API文档**：提供详细的API文档，帮助开发者理解和使用API。可以使用Swagger或Postman等工具生成文档。 - **自动化测试**：实施自动化测试框架，确保API的稳定性和可靠性。 ### 示例代码 以下是一个使用Python Flask设计RESTful API路由结构的示例： ```python from flask import Flask, jsonify, request app = Flask(__name__) # 模拟数据 users = [ {"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"} ] # 获取所有用户 @app.route('/api/v1/users', methods=['GET']) def get_users(): return jsonify(users) # 获取单个用户 @app.route('/api/v1/users/<int:user_id>', methods=['GET']) def get_user(user_id): user = next((user for user in users if user['id'] == user_id), None) if user is not None: return jsonify(user) else: return jsonify({"error": "User not found"}), 404 # 创建用户 @app.route('/api/v1/users', methods=['POST']) def create_user(): new_user = request.get_json() users.append(new_user) return jsonify(new_user), 201 # 更新用户 @app.route('/api/v1/users/<int:user_id>', methods=['PUT']) def update_user(user_id): user = next((user for user in users if user['id'] == user_id), None) if user is not None: data = request.get_json() user.update(data) return jsonify(user) else: return jsonify({"error": "User not found"}), 404 # 删除用户 @app.route('/api/v1/users/<int:user_id>', methods=['DELETE']) def delete_user(user_id): global users users = [user for user in users if user['id'] != user_id] return jsonify({"message": "User deleted"}) if __name__ == '__main__': app.run(debug=True) ``` ###
评论 4
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
红包 添加红包
表情包 插入表情
表情包 代码片
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值