用 Range 头拆分大响应：基于 http-api-design 的 HTTP API 分页与部分内容设计指南-北京尧图网络

API设计教程【免费下载链接】http-api-designHTTP API design guide extracted from work on the Heroku Platform API项目地址https://gitcode.com/gh_mirrors/ht/http-api-design点击查看免费下载导读本指南源自开源仓库 http-api-design即 Heroku Platform API 设计实践的提炼聚焦于如何用Range请求头把大响应拆分成多次请求返回这一基础设计原则。文章将说明何时应在响应中声明还有更多数据、客户端如何通过Range头精确获取后续数据并结合仓库内返回合适状态码、ETag 缓存等相关章节给出可落地、可引用的 HTTP API 分页方案。读完本文你将掌握 Range 分页的请求/响应头格式、状态码语义、数量限制、排序与迭代方法并能据此为自己的 API 设计出稳定且对客户端友好的大数据量读取接口。一、原则大响应必须被拆开在 divide-large-responses-across-requests-with-ranges.md 这一基础章节中仓库给出的核心结论非常明确Large responses should be broken across multiple requests usingRangeheaders to specify when more data is available and how to retrieve it.也就是说当一个资源列表或批量查询的响应体积过大时服务端不应一次性把所有数据塞进一个响应而应用Range头请求头允许客户端声明我要哪一段数据在响应中明确告诉客户端是否还有更多数据以及如何获取下一段。该文档进一步指出请求/响应头的具体格式、状态码、数量限制、排序与迭代细节参考 Heroku Platform API 关于 Ranges 的官方讨论文档原文引用了 devcenter.heroku.com 上 Platform API Reference 的 Ranges 章节。仓库本身将这一原则列为整个指南的Foundations基础之一可见其在整套 API 设计规范中的地基地位——后续所有涉及列表返回、批量查询的接口都应遵循它。二、为什么要用 Range 而不是其他分页方式在设计分页 API 时业界存在多种做法页码偏移量、游标、时间范围等。Range 方案的核心优势在于它复用 HTTP 语义、不引入私有参数与 HTTP 标准对齐Range头是 HTTP 协议中既有的概念常见于媒体内容的分段下载将其用于 API 列表分页语义清晰且客户端工具链成熟状态由响应声明是否还有更多数据、如何取下一段全部由服务端通过响应头显式告知客户端不需要自行推断这一页是否已到末尾支持属性范围查询不仅支持按内部 ID 排序分段还支持按任意可排序属性如名称分段天然适配按名称前缀查找等场景易于配合缓存与限流配合仓库中的 ETag 缓存、RateLimit 状态头等机制可构建完整的高质量列表接口。从仓库结构看该章节位于foundations/基础目录下与分离关注点、强制安全连接、在 Accepts 头中强制版本化等章节并列共同构成后续 Requests/Responses 章节的设计前提。三、Range 分页的请求与响应头设计依据该文档引用的 Heroku Platform API Ranges 规范Range 分页的核心设计要素如下。3.1 请求头Range客户端在请求列表资源时通过Range头声明自己需要的分段。两种常见形态按内部 ID 分段默认排序方式Range: id ..; max100按指定属性如名称分段Range: name ..; max100其含义是从排序后的开头..表示范围起始为空即从头开始取最多 100 条。客户端通过后续响应中的游标继续推进范围。3.2 响应头Content-Range与Next-Range服务端在响应中通过两个关键响应头向客户端交代当前段与后续数据Content-Range说明本次实际返回的属性范围与数据总量。例如按 ID 排序时Content-Range: id 0..99/1000表示本次返回的是第 0 到 99 条全量共 1000 条。当总条数未知时也可使用*代替总数如Content-Range: name a..m/*。Next-Range这是如何获取更多数据的关键。当还有更多数据时服务端返回该头其值为一个不透明的游标令牌客户端将其直接作为下一次请求的Range头使用即可无需理解内部含义Next-Range: id 100..; max100客户端下一轮请求只需原样携带该值Range: id 100..; max100如此循环直到响应中不再出现Next-Range即表示已迭代完所有数据。3.3 状态码语义200 与 206Range 分页的状态码设计与该仓库 return-appropriate-status-codes.md 章节的描述严格对应。该章节在成功状态码清单中专门写道200请求成功且本次响应完整返回了所请求的全部数据206请求成功但只返回了部分内容Partial Content——即服务端判定还有更多数据可返回。也就是说服务端在响应包含Next-Range暗示还有后续数据时应使用206 Partial Content状态码当本次响应已覆盖全部数据时使用200 OK。客户端可以通过状态码 Next-Range头的组合可靠判断数据是否取完从而正确结束迭代循环。四、限制、排序与迭代该文档明确指出Ranges 规范的细节覆盖了headers、status codes、limits限制、ordering排序与 iteration迭代五个维度。结合 Heroku Platform API 的公开规范可归纳为以下实战要点维度设计要点数量限制limits通过Range头中的max参数控制每段返回条数服务端对单段条数设置上限默认如 100 条最大不超过某个阈值如 1000 条防止单次响应过大排序ordering默认按资源 ID 排序可指定其他稳定、可比较的属性如名称作为分段依据保证分页结果一致、无重复、无遗漏迭代iteration客户端循环携带Next-Range游标发起后续请求直至响应不再包含Next-Range游标为不透明令牌服务端可自由演进内部实现头格式headers请求用Range响应用Content-Range与Next-Range全部遵循 HTTP 头命名规范不污染 URL 查询参数4.1 一个完整的迭代示例假设某apps列表接口全量有 1000 条记录服务端每段最多返回 100 条客户端的迭代过程如下第一步请求 GET /apps Range: id ..; max100 响应 HTTP/1.1 206 Partial Content Content-Range: id 0..99/1000 Next-Range: id 100..; max100 正文100 条记录第二步请求 GET /apps Range: id 100..; max100 响应 HTTP/1.1 206 Partial Content Content-Range: id 100..199/1000 Next-Range: id 200..; max100 正文100 条记录 …… 最后一步请求第 10 段 GET /apps Range: id 900..; max100 响应 HTTP/1.1 200 OK Content-Range: id 900..999/1000 正文最后 100 条记录不再有 Next-Range迭代结束注意最后一次响应因为已无后续数据状态码为200而非206——这与仓库 return-appropriate-status-codes.md 中对 200/206 的语义划分完全一致。五、与仓库其他基础原则的协同Range 分页不是孤立的设计它需要与仓库中其他基础与响应章节协同工作才能构成完整的大数据量读取方案返回合适状态码该章节在状态码清单中明确将206定义为GET 请求成功但仅返回部分响应并直接引用本 Range 章节作为依据原文为 see above on ranges。两者互为印证分页存在后续数据时返回 206全量返回时返回 200。支持 ETag 缓存给每个资源响应附带ETag客户端可用If-None-Match判断缓存是否过期。在 Range 分页场景下客户端可以对已取回的段做缓存减少重复传输。提供 Request-Id 用于追踪分页迭代会产生多次请求若每次响应都携带 UUID 形式的Request-Id配合客户端与后端日志可对整条迭代链路进行串联、诊断与调试。展示限流状态批量迭代本身就是高频请求场景服务端通过RateLimit-Remaining响应头告知剩余令牌数客户端可在令牌耗尽前暂停迭代避免触发 429。六、给 API 设计者的落地清单所有可能返回大量数据的列表接口一律支持Range请求头分段不提供一次性全量返回的裸路径每段响应明确给出Content-Range本次范围总量并仅在确有后续数据时返回Next-Range按 200全量/ 206部分语义返回状态码与仓库状态码章节保持一致用max参数限制每段条数并设置服务端上限保护服务健康使用稳定属性默认 ID排序保证迭代期间数据不重不漏迭代游标采用不透明令牌客户端只透传、不解析结合 ETag、Request-Id、RateLimit 头让分页接口可缓存、可追踪、可限流。七、进一步阅读本原则原文divide-large-responses-across-requests-with-ranges.md基础章节总览foundations/README.md状态码语义含 206 的定义与对本章节的引用return-appropriate-status-codes.md相关基础原则支持 ETag 缓存、提供 Request-Id相关响应规范展示限流状态、完整返回资源目录总览SUMMARY.md说明本文中关于Content-Range、Next-Range、max上限、排序与迭代等具体格式细节源自本仓库文档所引用的 Heroku Platform API Ranges 规范仓库内并未包含该规范的完整原文如需精确的头部取值与边界行为请以 Heroku Platform API Reference 的 Ranges 章节为准并在自有 API 中通过 OpenAPI 等机器可读规范固化这些约定。赞分享API设计教程【免费下载链接】http-api-designHTTP API design guide extracted from work on the Heroku Platform API项目地址https://gitcode.com/gh_mirrors/ht/http-api-design点击查看免费下载相关推荐FastEndpoints 仓库开发避坑指南从 AOT 发现、生成器契约到测试与 RPC 的 45 个关键细节FastEndpoints 仓库开发避坑指南从 AOT 发现、生成器契约到测试与 RPC 的 45 个关键细节 FastEndpoints 是一个面向 ASP后端Web框架API设计HTTP API 设计指南为 JSON 响应定义标准数据类型http-api-designHTTP API 设计指南为 JSON 响应定义标准数据类型http api design 导读本篇文章基于开源仓库 http api design hAPI设计教程HTTP API Range请求处理技术高效分页的终极指南HTTP API Range请求处理技术高效分页的终极指南 HTTP API设计中的 Range请求处理技术是处理大型响应数据的核心方法。通过使用RangeAPI设计教程上一篇Vosk 离线语音识别快速上手4 步在本地跑通语音转文字下一篇前端开发者必备的10大免费素材资源宝库从Unsplash到Pexels的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

用 Range 头拆分大响应：基于 http-api-design 的 HTTP API 分页与部分内容设计指南

相关推荐

VCR 请求匹配进阶：用 uri_without_param 忽略非确定性查询参数

Claude Code 上下文压缩（Compaction）机制解密：recent-messages 分析指令与 `＜analysis＞`/`＜summary＞` 摘要流程

DOM 元素搜索指南：掌握 JavaScript 教程中的 getElement* 与 querySelector* 方法

更多资讯

第088篇协程入门：suspend 到底挂起了谁

机房里通电正跑大模型的芯片，亚马逊转头打包卖了八十亿美元

动用七百多亿参数却只让百分之四干活，欧洲这只蜂鸟专治不懂装懂

以前总觉得「灯够亮」，直到孩子揉眼睛的频率越来越高

上班族备考公务员，每天只有两小时，到底够不够

GEMM 与 BLAS 全解：Tensor Core、CUDA、Transformer 的关系，各家 GPU 与框架的实现逻辑，以及投资机会

今日更新

Multisim仿真NE555 PWM控制器：从搭电路到调占空比全流程

S32K312 AUTOSAR BSW开发实战：从配置踩坑到烧录交付

双目视觉三维人脸重建：从视差图到点云粗配准全流程解析

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？