GitHub次级速率限制无文档，调试困难

说实话，GitHub文档只说了每小时5000次请求，但次级速率限制完全没有文档。触发403错误后，只能猜测是哪个限制，调试非常困难。

问题核心

文档缺失

官方文档：

• ✅ 主要限制：每小时5000次
• ❌ 次级限制：未提及
• ❌ 并发限制：未提及
• ❌ 端点限制：部分提及

问题：

• 开发者无法预判
• 触发限制后不知所措
• 调试成本高
• 影响开发效率

GitHub文档只说了每小时5000次请求，但次级速率限制完全没有文档。触发403错误后，只能猜测是哪个限制，调试非常困难。

问题分析

1. 文档不完整

缺失内容： | 限制类型 | 文档状态 | 影响 | |---------|---------|------| | 每分钟限制 | ❌ 无文档 | 高 | | 并发限制 | ❌ 无文档 | 高 | | 端点限制 | ⚠️ 部分文档 | 中 | | 资源限制 | ❌ 无文档 | 中 |

后果：

• 开发者无法合理规划
• 容易触发限制
• 调试困难
• 影响生产环境

2. 社区信息分散

信息来源：

• GitHub Community Forum
• Stack Overflow
• Reddit
• 个人博客

问题：

• 信息不权威
• 可能过时
• 难以验证
• 需要自己测试

3. 错误提示模糊

403错误：

{
  "message": "API rate limit exceeded",
  "documentation_url": "https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting"
}

问题：

• 不区分限制类型
• 不提供具体信息
• 不提示等待时间
• 难以针对性处理

4. 测试成本高

测试方法：

• 逐步增加请求频率
• 观察触发限制的阈值
• 记录限制规则
• 验证社区信息

时间成本：

• 单个限制：1-2小时
• 多个限制：1-2天
• 持续验证：持续进行

用户真实反馈

GitHub次级速率限制完全没有文档，我花了两天时间才搞清楚每分钟90次的限制。这种重要信息应该在文档里明确写出！

—— GitHub用户 @dev_user

我在Stack Overflow上找到了一些信息，但不知道是否准确。最后只能自己测试验证，浪费了很多时间。

—— Reddit用户 @api_dev

GitHub应该完善文档，明确说明所有速率限制。现在这样完全不透明，对开发者太不友好了。

—— 知乎用户 @github_user

已知的次级限制（社区总结）

1. 每分钟限制

规则：

• 每分钟最多90次请求
• 超过限制返回403
• 不区分端点

验证方法：

// 测试每分钟限制
let count = 0
const startTime = Date.now()

while (count < 100) {
  try {
    await github.repos.get({ owner: 'owner', repo: 'repo' })
    count++
  } catch (error) {
    if (error.status === 403) {
      console.log(`触发限制：${count}次/分钟`)
      break
    }
  }
}

2. 并发限制

规则：

• 同时进行的请求数有限制
• 具体数值不明确（约10-20个）
• 超过限制返回403

验证方法：

// 测试并发限制
const promises = []
for (let i = 0; i < 50; i++) {
  promises.push(github.repos.get({ owner: 'owner', repo: 'repo' }))
}

try {
  await Promise.all(promises)
} catch (error) {
  console.log('并发限制触发')
}

3. 端点特定限制

已知限制： | 端点 | 限制 | 来源 | |------|------|------| | 搜索API | 30次/分钟 | 官方文档 | | 创建Issue | 较低 | 社区测试 | | 创建PR | 较低 | 社区测试 | | GraphQL | 独立计算 | 官方文档 |

4. 资源密集型限制

触发条件：

• 大量数据查询
• 复杂搜索操作
• 批量创建操作

表现：

• 返回403错误
• 错误信息不明确
• 难以预判

现有解决方案对比

| 方案 | 实现难度 | 效果 | 推荐指数 | |------|---------|------|---------| | 保守策略 | 低 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | | 社区经验 | 低 | ⭐⭐⭐ | ⭐⭐⭐ | | 自己测试 | 高 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | | GitHub App | 中 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |

方案一：保守策略（推荐）

策略：

• 每分钟最多80次请求
• 并发最多10个请求
• 避免触发次级限制

优势：

• ✅ 简单易实现
• ✅ 避免触发限制
• ✅ 稳定可靠

实现：

const limiter = new RateLimiter({
  requestsPerMinute: 80,
  concurrentRequests: 10
})

await limiter.schedule(() => github.repos.get(...))

方案二：参考社区经验

信息来源：

• GitHub Community Forum
• Stack Overflow
• Reddit r/github
• 开发者博客

优势：

• ✅ 快速了解限制
• ✅ 学习他人经验

劣势：

• ❌ 信息可能过时
• ❌ 不够权威
• ❌ 需要验证

方案三：自己测试验证

测试流程：

1. 逐步增加请求频率
2. 记录触发限制的阈值
3. 总结限制规则
4. 持续验证更新

优势：

• ✅ 信息准确
• ✅ 适合自己场景

劣势：

• ❌ 时间成本高
• ❌ 可能影响生产环境

方案四：使用GitHub App

优势：

• ✅ 更高的限制（15000次/小时）
• ✅ 更宽松的次级限制
• ✅ 更好的错误提示

对比： | 类型 | 主要限制 | 次级限制 | 文档完善度 | |------|---------|---------|-----------| | Personal Token | 5000次/小时 | 90次/分钟 | ⭐⭐ | | GitHub App | 15000次/小时 | 更宽松 | ⭐⭐⭐⭐ | | OAuth App | 5000次/小时 | 90次/分钟 | ⭐⭐ |

最佳实践

1. 实现保守的速率限制

推荐配置：

const config = {
  // 主要限制
  requestsPerHour: 4500,  // 留500余量
  
  // 次级限制（保守估计）
  requestsPerMinute: 80,  // 留10余量
  concurrentRequests: 10,  // 并发限制
  
  // 端点限制
  searchPerMinute: 25,    // 搜索API
  createPerMinute: 30     // 创建操作
}

2. 监控和日志

监控指标：

// 记录请求
const logRequest = (endpoint, status) => {
  console.log({
    timestamp: new Date(),
    endpoint,
    status,
    remaining: response.headers['x-ratelimit-remaining']
  })
}

// 定期报告
setInterval(() => {
  console.log('请求统计:', stats)
}, 60000)

3. 错误处理

完整处理：

async function safeRequest(fn) {
  try {
    return await fn()
  } catch (error) {
    if (error.status === 403) {
      // 检查是否是主要限制
      const remaining = error.headers['x-ratelimit-remaining']
      if (remaining === '0') {
        // 主要限制，等待重置
        const reset = error.headers['x-ratelimit-reset']
        const waitTime = reset * 1000 - Date.now()
        await sleep(waitTime)
        return await fn()
      } else {
        // 次级限制，指数退避
        await sleep(60000)  // 等待1分钟
        return await fn()
      }
    }
    throw error
  }
}

4. 向GitHub反馈

反馈渠道：

• GitHub Community Forum
• GitHub Support
• GitHub Feedback

建议内容：

• 完善次级限制文档
• 改进错误提示
• 提供限制监控API

---

你遇到过GitHub次级速率限制问题吗？ 欢迎在评论区分享你的经历和解决方案。