GitHub Search API分页结果数量不稳定的原因与解决方法

问题原因 #

你遇到的每页结果数量不固定是GitHub Search API的正常行为，主要原因包括：

• 部分匹配的文件来自私有仓库，你没有访问权限，因此不会出现在返回结果中
• 搜索结果总数不足100条（比如特定size区间的匹配文件较少）
• GitHub代码搜索API存在1000条结果上限，超过这个数量的部分无法获取，即使total_count显示更多
• API内部的去重或结果过滤逻辑导致部分匹配项被排除

你并没有错误使用API，这种情况是设计特性而非bug。

正确的处理方案 #

不需要重复执行查询，而是基于API的返回结果动态处理分页：

1. 利用API返回的关键字段判断 #

• total_count：匹配搜索条件的总结果数（注意：若总数超过1000，该值仅作参考，实际最多只能获取1000条）
• items：当前页的结果列表，长度可能小于per_page设置值
• 响应头中的Link：包含下一页、上一页的API地址，用它来分页比手动拼接page参数更可靠

2. 代码实现示例 #

import requests

def fetch_all_code_results(query):
    url = f"https://api.github.com/search/code?q={query}&per_page=100"
    headers = {'Authorization': 'Token xxxxxxxxxxxxxxxxxxxxxxxxxxxxx'}
    all_items = []
    
    while url:
        response = requests.get(url, headers=headers)
        response.raise_for_status()  # 处理请求错误
        data = response.json()
        
        all_items.extend(data['items'])
        # 检查是否有下一页
        links = response.headers.get('Link', '')
        url = None
        for link in links.split(','):
            if 'rel="next"' in link:
                url = link.split(';')[0].strip('<>')
                break
        
        # 达到代码搜索的1000条上限时停止
        if len(all_items) >= 1000:
            break
    
    return all_items

# 示例调用：搜索指定size区间的文件
query = "torch +in:file +language:python+size:0..250"
results = fetch_all_code_results(query)
print(f"总共获取到 {len(results)} 条结果")

3. 注意事项 #

• 遵守GitHub API的速率限制：认证用户每小时最多可进行30次代码搜索请求，避免频繁请求导致被限制
• 若total_count远大于1000，说明你无法获取全部匹配结果，这是API的硬限制，无法绕过
• 不要假设每页必返回100条结果，始终以实际返回的items长度为准，动态累加结果

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