Lychee链接检查工具处理GitHub请求限制的技术解析

在使用Lychee链接检查工具对包含大量GitHub链接的文档进行检查时，开发者可能会遇到"Too Many Requests"的错误提示。这种情况通常与GitHub API的请求限制有关，即使已经配置了有效的GitHub令牌。

问题本质分析

GitHub API对未认证请求的速率限制为每小时60次，而使用GITHUB_TOKEN认证后，限制会提升至每小时1000次请求（按每个仓库计算）。当检查的文档中包含大量GitHub链接时（例如700个），很容易触发这个限制。

现有解决方案

Lychee目前提供了几种缓解速率限制的方法：

1. 并发控制：通过--max-concurrency参数可以限制同时进行的请求数量。将其设置为较低值（如1）可以延长达到速率限制的时间，但不能从根本上解决问题。

2. 缓存机制：使用--cache参数可以缓存已检查的链接结果，避免重复请求相同的资源。

3. 链接过滤：结合--include或--exclude参数可以只检查特定类型的链接，减少不必要的API调用。

技术局限性

当前版本的Lychee存在以下技术限制：

1. 缺乏自动的按主机速率限制功能，无法智能地为不同域名分配请求配额。

2. 连续运行检查时，请求计数会累积，可能导致后续运行更快达到限制。

3. 对于包含大量GitHub链接的文档（如开源项目贡献者列表），即使采取上述措施，仍可能有部分链接检查失败。

最佳实践建议

针对检查GitHub链接的场景，建议采取以下策略：

1. 对于大型文档，分批进行检查，避免一次性触发速率限制。

2. 合理利用缓存功能，特别是对不常变动的资源（如用户资料）。

3. 考虑将检查任务分散到不同时间段执行。

4. 监控返回的429错误数量，作为调整检查策略的依据。

未来改进方向

Lychee开发团队已经将按主机速率限制功能列入开发计划。这一改进将允许工具为不同域名（如github.com）智能分配请求配额，从根本上解决此类问题。在此之前，开发者需要结合现有功能和检查策略来优化链接验证流程。

对于需要频繁检查大量GitHub链接的场景，建议关注项目更新，等待更完善的速率限制机制发布。