用途
该技能用于处理 Apify API 的速率限制（rate limits），在遇到 429 错误、优化 API 请求吞吐量或实现请求排队时使用。Apify API 按资源维度强制执行速率限制，apify-client 库会自动重试 429 响应（最多 8 次，采用指数退避），因此大多数工作负载不会察觉到限制。当批量操作、自定义 API 调用或大规模扇出超出内置重试的承受能力时，就需要借助该技能，通过批处理、排队、错峰和监控来保持在限制之下。
速率限制规则
- 按资源（默认）：60 请求/秒，分别适用于每个 Actor、数据集、KV 存储。
- 数据集推送：每个数据集 60 请求/秒，建议批量推送以减少调用次数。
- Actor 运行：每个 Actor 60 请求/秒，建议按顺序或带延迟启动运行。
- 平台整体：存在更高的聚合限制，跨所有资源累计。
“按资源”意味着对数据集 A 和数据集 B 的调用各自独立享有 60 请求/秒。每个响应都携带 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset（epoch 秒）响应头。
前置条件
- 拥有 API 访问权限的 Apify 账户，并在环境中设置 APIFY_TOKEN。
- 已安装 apify-client 包（npm install apify-client）。
- 如需自定义排队：p-queue（npm install p-queue）；crawlee 用于 sleep 和爬虫级并发控制。
使用方式
工作流共五步，每一步的核心手段如下，完整可运行代码见 implementation.md，组合场景见 examples.md。
- 理解内置重试：apify-client 已对 429/500+ 采用指数退避重试。仅当默认值不适合你的端点时，才调整 maxRetries / minDelayBetweenRetriesMillis：
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({
token: process.env.APIFY_TOKEN,
maxRetries: 5, // Default: 8
minDelayBetweenRetriesMillis: 500, // Default: 500
});
- 批量操作（最有效的手段）：将逐项循环合并为一次批量调用（最大 9 MB），仅在数据集非常大时才分块：
await client.dataset(dsId).pushItems(items); // 1 call, not N
-
排队自定义调用：通过 p-queue（concurrency + intervalCap）对原始 API 调用进行门控，使扇出读取不超过 60 请求/秒。详见 implementation.md 第 3 步。
-
错开 Actor 启动：在 start() 调用之间插入约 200 毫秒延迟，使 runs 端点不会触发 429，然后并行 waitForFinish()。详见 implementation.md 第 4 步。
-
监控响应头：将 X-RateLimit-* 输入一个小型监控器，在触顶前发出警告，并精确暂停到重置时刻。详见 implementation.md 第 5 步。
目标网站的限流是独立于平台 API 的另一道上限，可通过 Crawlee 的 maxConcurrency / maxRequestsPerMinute 进行限制（见 implementation.md 的 Crawlee 级并发部分）。
输出
应用该技能后会产生一个具备速率感知能力的 Apify 集成：
- 配置了显式重试范围的 ApifyClient。
- 批量/分块的数据集写入，将 API 调用次数降低数个数量级。
- 经 p-queue 门控的调用路径，使每个资源的请求保持在 60 请求/秒以下。
- 错开的 Actor 启动，以及可选的、由响应头驱动的监控器，在耗尽前暂停——最终效果是在负载下实现零 429（或被透明重试）。
错误处理
- API 429：apify-client 自动重试，通常透明；若持续出现则增加延迟。
- 目标站点 429：在处理器中检测 statusCode === 429，降低 maxConcurrency，添加代理轮换。
- 启动突发：一次启动 100+ 个运行，用 200 毫秒延迟错开。
- 大数据推送：单次 50MB 数据集推送，分块为 9MB 批次。
示例
完整端到端场景见 examples.md：
- 无 429 的批量数据集推送——50,000 行通过分块批处理约 50 次调用完成。
- 通过队列进行扇出读取——500 次 Actor 读取保持在 50 请求/秒以下。
- 安全启动 100 个运行——错开启动，然后并行等待完成。
- 基于响应头驱动的耗尽暂停——精确休眠到限制重置。
资源
- Apify API Rate Limits
- p-queue Documentation
- Crawlee Auto-scaling
安全配置请参见 apify-security-basics。