前两篇说的都是「证据看着齐了，其实不可信」。这一篇是最干净的一种：

你的判据全绿，数据是残的，而你手上唯一一个能发现这件事的字段，正在告诉你「结果是完整的」。

场景极常见：你写了个脚本扫 GitHub。HTTP 200，没有报错，拿到结果，判据通过。

    r = requests.get(url, params={"q": query, "per_page": 1000})

    assert r.status_code == 200          # 通过

    results = [x["name"] for x in data["items"]]   # 拿到 100 条

代码每一行都对。但 per_page=1000 没有生效，你拿到的是 100 条。

⚠️ 口径先钉住：本篇的每一条数字，都是我今天亲手实跑公开 API 得到的，

文档引用逐条核过原文。全部匿名、零登录。没有一条是从博客里搬的。

GitHub REST API 文档的「Changing the number of items per page」一节，原文：

For most endpoints, the maximum value of per_page is 100.

If you specify a value greater than the maximum, GitHub does not return an error.

Instead, the value is automatically reduced to the maximum, and the response

includes no more than the maximum number of results per page.

Because the request still succeeds, you may receive fewer results than you expect

without any indication that the per_page value was reduced.

  the value is automatically reduced   悄悄改了你的参数

  without any indication   没有任何提示

「without any indication」是文档自己写的。 不是我推测的，是 GitHub 明说「不会给你任何提示」。

文档说了不算，行为今天还在才算。我对同一个端点传三个不同的 per_page：

    GET https://api.github.com/repos/torvalds/linux/commits?per_page=100

    GET https://api.github.com/repos/torvalds/linux/commits?per_page=1000

    GET https://api.github.com/repos/torvalds/linux/commits?per_page=5000

  请求   HTTP   返回条数   响应体字节数

三个字节数一模一样。 不是「大概差不多」，是逐字节相同——同一条响应。

5000 和 100 返回了完全相同的 509912 字节。没有任何一处不同。

    link: <https://api.github.com/repositories/2325298/commits?per_page=5000&page=2>; rel="next",

           <https://api.github.com/repositories/2325298/commits?per_page=5000&page=14848>; rel="last"

它把你写的 per_page=5000 原样回显回来了。

信号全是绿的：200、没有 Warning、限额头正常、Link 头还贴心地告诉你总共 14848 页。

唯一做错的那个参数，在回显里看起来像是生效了。

三、最狠的一层：那个字段正在说谎

上面那个端点还算仁慈——它返回一个纯数组，你没机会发现。

但 search 端点不一样。search 的返回是个对象，里面有个 total_count。

很多人的判据就写在这儿。这个字段本该是你的救命稻草：

    GET https://api.github.com/search/repositories?q=stars:>100&per_page=1000

- total_count: 478953 —— 「符合条件的有 47 万条」

- incomplete_results: false —— 「结果完整」

等一下。 47 万 vs 100 条，差了几千倍。这个端点自己都告诉你少了。

而 incomplete_results 告诉你 false。

这个字段是有意义的。看文档第 80–88 行，「Timeouts and incomplete results」一节：

For queries that exceed the time limit, the API returns the matches that were already

found prior to the timeout, and the response has the incomplete_results property set to true.

所以 incomplete_results 是专门用来告诉你「结果不完整」的字段。

它只在查询超时时置 true。而 per_page 截断跟超时是两回事，所以它不会置 true。

于是形成一个闭环，这是本篇最要紧的一句：

你越是信任 incomplete_results 这个判据，你越是确信自己的结果是完整的。

这条判据不但没能救你，它还反过来给你盖章。

我换了两条查询复验，这不是单次巧合：

  查询   total_count   items   incomplete_results

  language:python   34472264   100   false

第三次：三千四百四十二万条符合条件，给了 100 条，incomplete_results 说是完整的。

GitHub 完全可以在 per_page=1000 时返回 400 Bad Request，一句话就解决了。

对上游来说这是合理的工程选择：这个行为对绝大多数调用者是无害的。

如果你只是想翻前几页，100 条够用，多给的参数被忽略，你根本不会察觉，也没有任何损失。

但对把数字当判据用的人来说，这个设计正好落在最坏的位置。

    上游把参数改成 100        ← 静默

    返回 100 条 + HTTP 200    ← 你的判据全过

    incomplete_results=false  ← 判据二也过了

    你写下「该仓库 100 个 star 高星项目」

最后那行是我编的，但那正是它在你代码里长出来的样子。

问题不在于「少了 900 条」。问题在于：

这个数据从离开上游到进入你的结论，中间经过了每一层它本该被拦住的检查，没有一层把它拦住。

- 完整性检查：看 incomplete_results → false → 放行

- 数量检查：len(items) 有值 → 放行

四道关卡，全部按它们被设计时的意图正确工作。

只有你恰好知道 per_page 上限是 100，才会发现不对。而这条知识——

按 GitHub 自己的说法——不给你任何提示。

五、同一份设计里的另一个静默口子

GitHub 的 search 文档里还有两处同类设计，同一个思路：

To keep the REST API fast for everyone, we limit the number of repositories a query

will search through. The REST API will find up to 4,000 repositories that match

your filters and return results from those repositories.

搜到 4,000 个仓库就停了。后面还有没有，不告诉你。

无权访问的资源（第 94 行，原文加粗）：

When your search query requests multiple resources, the response will only contain

the resources that you have access to and will not provide an error message

listing the resources that were not returned.

你请求了 5 个仓库，你只能看 2 个。不报错、不列清单，那 3 个直接消失。

三处放在一起看，能看出一个一致的原则：

GitHub 选择「让请求成功」而不是「让请求准确」。

这个取舍我不批评，它有它的道理。但作为调用方，你得知道：

在这套 API 上，「成功」和「你拿到了全部」是两件事。

分两种情况，能不能自查取决于返回结构。

search 端点：有一个可靠的交叉判据

因为它同时给 total_count 和 items，你可以直接比：

        """把 GitHub 搜索的分页拿全，并且能发现自己有没有拿全。"""

            r = requests.get("https://api.github.com/search/repositories",

                             params={"q": query, "per_page": per_page, "page": page},

            # 判据一：官方那个 incomplete_results 标志位

                raise RuntimeError(f"第 {page} 页查询超时，结果不完整，别用")

            # 判据二：拿到的条数对不上总数——这就是静默截断

            if len(d["items"]) < per_page and page > 1:

        # 判据三：最终条数必须等于它自己说的总数

            raise RuntimeError(f"只拿到 {len(out)} 条，但接口说有 {total} 条")

判据三是关键。 它不看任何自我声明的标志位，

而是拿「它宣称的数量」和「你实际拿到的数量」对账。

这个口径不依赖上游给不给提示。

⚠️ 但这个判据也不是完美的，README 里写明的 4,000 仓库扫描上限会让

total_count 本身就偏小——那时候 total_count 和实际可搜到的量一致，

但它不是全网总量。所以判据三能防截断，防不了扫描范围上限。这两件事得分开看。

像 /repos/.../commits 这种，返回的是纯数组，连 total_count 都没有。

我实测过它的每一条 commit 对象的键：

    author, comments_url, commit, committer, html_url, node_id, parents, sha, url

没有任何一个字段跟数量有关。

这种端点上唯一可靠的做法：别猜上限，直接传 100，并且把分页跑到底。

然后如果你想知道「到底还有没有」，只能顺着 Link 头的 rel="last" 走完。

    # 用 rel="last" 拿真实页数，不信你传进去的参数

        r = requests.get(url, params={"per_page": per_page}, timeout=30)

        last = re.search(r'page=(\d+)>;\s*rel="last"', link)

        return int(last.group(1)) if last else 1

1. GitHub 为什么要这么设计，我没找到他们的内部说明。

   文档只说「让 API 保持快」，没说为什么不报错。本篇讲的形状，

2. 这个降级从哪个版本开始，我没查 changelog。

3. total_count 本身有多可靠，我没测。

   我测了它跟 items 对不上，但没测它跟「全网真实命中数」对不对得上。

   第六节说了，4,000 仓库上限会让它偏小。

4. 我没跑过批量场景。 三次查询都是单发，不是高并发下的行为。

   高并发时会不会返回别的错误，我没验。

5. 其他 API 平台（GitLab / Gitee / npm registry）有没有同样的静默降级，

   本篇一个字都没说。 这是个合理的延伸问题，但我没做，别外推。

一手（本轮我亲自实跑 / 取全文核对）

  per_page 超上限不报错、自动降级、「without any indication」   docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api「Changing the number of items per page」节   已取全文，原文逐字核对

  per_page=100/1000/5000 三次均返回 100 条、509912 字节、HTTP 200   api.github.com/repos/torvalds/linux/commits，本轮实测   已实跑，三次字节数相同

  Link 头原样回显 per_page=5000   同上响应头   已实跑

  total_count=478953 / items=100 / incomplete_results=false   api.github.com/search/repositories?q=stars:>100&per_page=1000   已实跑

  另两次复验（65355 / 34472264）   stars:>1000、language:python   已实跑，同样是 100 + false

  commit 对象无任何数量字段   同列表端点返回体，键名实测   已实跑

  incomplete_results 仅超时置 true   raw.githubusercontent.com/github/docs/main/content/rest/search/search.md 第 82–88 行   已取全文

  up to 4,000 repositories 扫描范围上限   同文件第 78 行「Search scope limits」节   已取全文

  无权资源「will not provide an error message」   同文件第 94 行「Access errors or missing search results」节   已取全文

以上全部为匿名访问，无需登录。

本篇不成立的结论（免得被过度引用）

1. 不能说 GitHub 的 API 不可信。 它做的是它选的那个取舍，

   而且它把这件事写在了文档里，包括「不会给你任何提示」这句。

   本篇讲的是你从这个设计里能不能察觉，不是它对不对。

2. 不能说所有端点都有 per_page。 文档写的是

   For most endpoints——「大多数」，不是全部。

   我实测的两个端点都有，但没有穷举。

3. 不能说 total_count 是错的。 我测到的是它跟 items 对不上，

   这说明你不能用 items 的条数推 total_count，或者反过来。

   我没有验证 total_count 跟真实命中数是否一致（见第七节第 3 条）。

4. 不能说 incomplete_results 坏了。 它按设计工作——

   它只管超时。per_page 截断不在它的职责范围内。

   本篇说的是：拿它当完整性判据是误用。

5. 不能说我的代码示例能直接用。 第六节那两个函数我没有在生产环境跑过，

   第六节末尾自己也写了判据三防不了 4,000 上限。

我让 GitHub 一次给我 1000 条，它给了我 100 条，还告诉我结果是完整的

写脚本扫 GitHub 时，per_page=1000 不会生效，也不会有任何提示。我对同一个端点传 per_page=100、1000、5000，三次都返回 HTTP 200、都只给 100 条，响应体字节数完全相同（509912，逐字节相同）；Link 头还把 per_page=5000 原样回显。GitHub 文档自己写着「does not return an error」「without

编程语言

开发工具

新闻资讯

GitHub API静默截断：per_page超过100自动降级不报错，incomplete_results仅检测超时，导致HTTP 200、全绿判据下数据缺失。实测5000与100返回同字节响应，total_count与items数量相差数千倍。本文提供对账校验法：比对声明总数与实际获取数，识别静默截断，并实测验证三处同类设计。

GitHub

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

GitHub API静默截断：per_page超过100自动降级不报错，incomplete_results仅检测超时，导致HTTP 200、全绿判据下数据缺失。实测5000与100返回同字节响应，total_count与items数量相差数千倍。本文提供对账校验法：比对声明总数与实际获取数，识别静默截断，并实测验证三...

我让 GitHub 一次给我 1000 条，它给了我 100 条，还告诉我结果是完整的

我让 GitHub 一次给我 1000 条，它给了我 100 条，还告诉我结果是完整的

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐