API Platform中pagination_items_per_page与pagination_maximum_items_per_page的区别

两个配置的核心作用 #

• pagination_items_per_page：分页默认返回条数，当客户端请求接口时没有主动指定itemsPerPage参数时，接口默认按该配置值返回每页数据。
• pagination_maximum_items_per_page：分页最大允许返回条数上限，默认值~代表无限制，配置后客户端主动指定的itemsPerPage参数不能超过该值，超过时会自动降级为该配置值返回。

pagination_maximum_items_per_page的适用场景 #

这个参数的核心价值是做接口防护和业务约束，通常在以下场景需要配置：

1. 防止恶意请求拖垮服务：如果不设置上限，攻击者可以直接请求itemsPerPage=10000甚至更大的数值，触发超大SQL查询，占用大量数据库、应用服务器资源，最终导致服务不可用。配置上限后就算传入超大的条数参数，也只会按上限查询返回，避免资源耗尽。
2. 防止数据批量爬取：如果业务不允许用户一次性拉取全量接口数据，设置该参数可以强制所有分页请求最多返回指定条数，避免爬虫一次性拉走全量数据。
3. 统一业务规则约束：部分业务场景下对单页数据量有明确规则要求，配置该参数可以做全局强制限制，避免前端或者客户端开发传参不合理导致的体验问题。

示例配置效果 #

如果你有如下配置：

api_platform:
    defaults:
        pagination_items_per_page: 30
        pagination_maximum_items_per_page: 100

实际请求的效果如下：

• 客户端不传itemsPerPage参数：接口按默认值返回每页30条数据
• 客户端传itemsPerPage=50：参数值低于上限，接口返回每页50条数据
• 客户端传itemsPerPage=200：参数值超过上限，接口自动按最大值返回每页100条数据

内容的提问来源于stack exchange，提问作者Robin Bastiaan