API 响应体中是否应当包含 offset 与 limit 分页参数？

结论 #

在响应体中同步返回limit和offset属于通用最佳实践，绝非冗余内容，核心作用是解决参数不一致、上下文丢失、调试困难三类常见问题。 #

具体作用 #

• 对齐实际执行参数，避免分页逻辑出错
  很多API会对分页参数做默认赋值、范围限制、非法值修正逻辑：比如你请求limit=1000，但接口后台配置了单次最多返回200条，会自动把limit修正为200；再比如你传了负数offset，接口会自动修正为0。如果只依赖客户端自己保存的请求参数计算下一页偏移量，必然会出现跳页、漏数据、重复拉取的问题，只有响应中返回接口实际执行的分页参数，才能保证分页逻辑的正确性。
• 适配无状态场景，降低客户端维护成本
  很多场景下客户端不会持久化存储请求参数：比如响应结果被CDN/网关缓存、请求被中间层转发、异步回调时上下文丢失、多端共享分页响应数据。直接从响应里取limit和offset就能直接计算下一页/上一页的请求参数，不需要客户端单独维护分页状态，大幅减少状态不一致导致的bug。
• 降低调试排查成本
  前后端联调、线上问题排查时，不需要翻查请求日志，仅通过响应内容就能快速确认当前返回的分页区间是否正确，大幅提升问题定位效率。

参考示例 #

示例请求 #

baseUrl.com/api/data?limit=50&offset=100

示例响应 #

{
  "totalResults": 100000,
  "limit": 50,
  "offset": 100,
  "count": 50,
  "items": [ ]  
}

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