REST API分页场景下HTTP 206 Partial Content适用条件咨询

背景 #

我们团队提出在REST API中使用状态码206 - Partial Content的方案：针对大数据集的GET请求，若存在未返回的剩余内容则返回该状态码，以此支持API使用者实现分页，替代当前我们在响应体中使用的hasMore标识方案。

方案优势

• 使用通用标准状态码可让API使用者依托通用HTTP规范交互，无需学习我方自定义的专属规则。
• 有观点认为该状态码非常适合用来标识是否存在更多剩余结果。

方案争议

• 所有请求均携带pageSize数值型查询参数，当前响应已返回该参数指定数量的全部结果，此时返回206 - Partial Content可能不符合语义规范。
• 有观点指出206 - Partial Content通常用于字节流场景，而非集合列表的分页场景。

咨询问题 #

在响应RESTful风格GET请求返回分页结果集的场景下，哪些情况可以或应当使用206 - Partial Content实现结果集分页？

回答 #

直接给结论：206 Partial Content不是完全不能用于集合分页，但有严格的适用边界，你们目前设想的「只要有剩余数据就返回206替代hasMore」的方案属于典型的语义误用，不建议落地。

先明确HTTP规范对206的核心要求：根据RFC 7233的定义，206的触发前提是客户端主动携带Range请求头发起范围请求，服务端按请求指定的范围返回对应内容时才能返回该状态码。脱离Range请求头随意返回206属于违反HTTP语义的行为，通用HTTP组件（浏览器、标准HTTP SDK、中间代理、缓存服务）都不会按你预期的逻辑处理，甚至可能出现响应解析错误。

具体到分页场景，只有两类情况可以/应当使用206：

• 你在API文档中明确声明支持自定义集合范围单位，且客户端确实通过Range请求头指定了要获取的条目范围。比如你定义支持items作为范围单位，客户端请求时携带Range: items=0-24表示要取索引0到24的共25条数据，此时你返回对应范围的结果，就可以返回206，同时必须携带Content-Range响应头，格式参考Content-Range: items 0-24/1356，斜杠后是集合总条目数，总条数未知时可以填*。这种用法完全符合HTTP规范的扩展要求——RFC从未限制Range只能用于字节流，允许自定义范围单位，只是这类扩展必须明确告知调用方，不能私自实现。
• 分页返回的内容本身就是二进制字节流，比如大文件分片下载、超大数据集导出的流式响应，这时候用原生的字节Range做分片断点续传，本身就是206的原生设计场景，和分页逻辑完全契合，不存在任何语义问题。

再明确下你们当前方案的核心问题：
你们现有的分页逻辑是客户端传pageSize参数，服务端返回指定数量的结果，整个请求响应流程没有Range头参与，哪怕你确实只返回了部分数据，也不满足206的触发前提。这种场景下返回200状态码，在响应体中携带hasMore、总条数等分页字段是行业通用做法，根本不存在「自定义规则不通用」的问题——所有做过API开发的使用者都能快速理解，反倒是乱用206会让熟悉HTTP规范的开发者产生困惑，还可能引发客户端兼容问题。

如果要使用206做分页，两个强制要求缺一不可：

• 必须由客户端主动发起带Range头的范围请求，不能是服务端主动截断分页就返回206
• 返回206时必须携带Content-Range响应头，明确标注当前返回内容的范围、资源总长度，不能只返回状态码不提供范围信息

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