Rate Limiting API 允许您定义速率限制,并在 Worker 中围绕它们编写代码。
速率限制是近似值,并且会在每个 Cloudflare 位置分别应用。计数在后台更新期间,请求可能会超过你配置的限制。如需跨位置实施严格限制,请参阅严格限制。
您可以使用它来强制执行:
- 在 Worker 启动后应用的速率限制,仅在代码的特定部分被到达时才生效
- 针对不同类型客户或用户(例如:免费 vs. 付费)的不同速率限制
- 针对特定资源或路径的限制(例如:每个 API 路由的限制)
- 以上任意组合
Rate Limiting API 由为 rate limiting rules 提供服务的相同基础设施支持。
首先,向 Worker 添加一个绑定(binding),使其能够访问 Rate Limiting API:
{
"main": "src/index.js",
"upload_source_maps": true,
"ratelimits": [
{
"name": "MY_RATE_LIMITER",
// An identifier you define, that is unique to your Cloudflare account.
// Must be an integer.
"namespace_id": "1001",
// Limit: the request threshold within a given period in a single
// Cloudflare location. Requests can exceed this threshold.
// Period: the duration of the period, in seconds. Must be either 10 or 60
"simple": {
"limit": 100,
"period": 60
}
}
]
}main = "src/index.js"
upload_source_maps = true
[[ratelimits]]
name = "MY_RATE_LIMITER"
namespace_id = "1001"
[ratelimits.simple]
limit = 100
period = 60此绑定使 MY_RATE_LIMITER 绑定可用,它提供 limit() 方法:
export default {
async fetch(request, env) {
const { pathname } = new URL(request.url)
const { success } = await env.MY_RATE_LIMITER.limit({ key: pathname }) // key can be any string of your choosing
if (!success) {
return new Response(`429 Failure – rate limit exceeded for ${pathname}`, { status: 429 })
}
return new Response(`Success!`)
}
}interface Env {
MY_RATE_LIMITER: RateLimit;
}
export default {
async fetch(request, env): Promise<Response> {
const { pathname } = new URL(request.url)
const { success } = await env.MY_RATE_LIMITER.limit({ key: pathname }) // key can be any string of your choosing
if (!success) {
return new Response(`429 Failure – rate limit exceeded for ${pathname}`, { status: 429 })
}
return new Response(`Success!`)
}
} satisfies ExportedHandler<Env>;limit() API 接受单个参数——一个包含 key 字段的配置对象。
- 您提供的 key 可以是任何
string值。 - 一种常见模式是通过组合唯一标识发起请求的执行者(例如:用户 ID 或客户 ID)的字符串和标识特定资源的字符串(例如:特定 API 路由)来定义 key。
您可以为每个 Worker 定义和配置多个速率限制配置,这允许您根据需要针对传入请求和/或用户参数定义不同的限制,以保护您的应用程序或上游 API。
例如,以下是如何为免费和付费层级用户定义两个速率限制配置:
{
"main": "src/index.js",
"upload_source_maps": true,
"ratelimits": [
// Free user rate limiting
{
"name": "FREE_USER_RATE_LIMITER",
"namespace_id": "1001",
"simple": {
"limit": 100,
"period": 60
}
},
// Paid user rate limiting
{
"name": "PAID_USER_RATE_LIMITER",
"namespace_id": "1002",
"simple": {
"limit": 1000,
"period": 60
}
}
]
}main = "src/index.js"
upload_source_maps = true
[[ratelimits]]
name = "FREE_USER_RATE_LIMITER"
namespace_id = "1001"
[ratelimits.simple]
limit = 100
period = 60
[[ratelimits]]
name = "PAID_USER_RATE_LIMITER"
namespace_id = "1002"
[ratelimits.simple]
limit = 1_000
period = 60速率限制绑定具有以下设置:
| 设置 | 类型 | 描述 |
|---|---|---|
namespace_id |
string |
包含正整数的字符串,在您的 Cloudflare 账户内唯一标识此速率限制命名空间(例如 "1001")。虽然值必须是有效整数,但指定为字符串。这是有意为之。 |
simple |
object |
速率限制配置。simple 是唯一支持的类型。 |
simple.limit |
number |
针对每个 Cloudflare 位置,在指定 period 内调用 limit() 的请求阈值。请求可能会超过此阈值;请参阅准确性。 |
simple.period |
number |
速率限制窗口的持续时间,以秒为单位。必须是 10 或 60。 |
如果您不想在绑定之间共享速率限制状态,请为每个绑定使用唯一的 namespace_id。
:::
例如,要应用每分钟 1500 个请求的速率限制,您可以按如下方式定义速率限制配置:
{
"ratelimits": [
{
"name": "MY_RATE_LIMITER",
"namespace_id": "1001",
// 1500 requests - calls to limit() increment this
"simple": {
"limit": 1500,
"period": 60
}
}
]
}[[ratelimits]]
name = "MY_RATE_LIMITER"
namespace_id = "1001"
[ratelimits.simple]
limit = 1_500
period = 60传递给 limit 函数、用于确定速率限制依据的 key,应代表您希望进行速率限制的用户或用户类别的唯一特征。
- 好的选择包括
AuthorizationHTTP 标头中的 API 密钥、URL 路径或路由、应用程序使用的特定查询参数,和/或用户 ID 和租户 ID。这些都是稳定的标识符,在请求之间不太可能改变。 - 不建议使用 IP 地址或位置(区域或国家),因为在许多有效情况下,这些可能被许多用户共享。您可能会发现自己在这些 key 上进行速率限制时,无意中限制了比预期更广泛的用户群体。
// Recommended: use a key that represents a specific user or class of user
const url = new URL(req.url);
const userId = url.searchParams.get("userId") || "";
const { success } = await env.MY_RATE_LIMITER.limit({ key: userId });
// Not recommended: many users may share a single IP, especially on mobile networks
// or when using privacy-enabling proxies
const ipAddress = req.headers.get("cf-connecting-ip") || "";
const { success } = await env.MY_RATE_LIMITER.limit({ key: ipAddress });您在 Worker 中定义和强制执行的速率限制是本地于 Worker 运行的 Cloudflare 位置 ↗的。
例如,如果你为特定路径配置了每 60 秒 100 个请求,悉尼处理的请求会计入悉尼的限制。在另一个 Cloudflare 位置处理的请求会计入单独的限制,即使它们使用相同的命名空间和键也是如此。这些计数不会合并成一个全球限制。
每个位置分别应用近似限制。如准确性所述,同一位置中的请求可能会超过配置的阈值。
Workers 中的 Rate Limiting API 设计为快速。
每次检查都会使用本地缓存的计数。Cloudflare 会在同一位置的后台更新共享计数。
这意味着在代码中 await 对 limit() 方法的调用时:
const { success } = await env.MY_RATE_LIMITER.limit({ key: customerId });Promise 会根据速率限制决定结果进行解析。它不会等待所有运行中的实例完成计数同步,因此你可以在无需等待同步的情况下检查限制。
Rate Limiting API 提供的是近似限制。计数最终会保持一致:每次检查使用本地计数,更新会在后台传递到其他运行中的实例。
更新到达前,请求可能会超过配置的限制。在单个或多个 Worker 中都可能发生此情况,即使同一 Cloudflare 位置的每个请求使用相同的命名空间和键也是如此。
下图展示了针对同一命名空间和键进行的两次本地检查。计数同步前,两次检查都可能允许请求:
flowchart TD
accTitle: 本地速率限制检查与后台更新
accDescr: 在一个 Cloudflare 位置内,发往一个或多个 Workers 的请求会检查同一命名空间和键的本地计数。在后台更新将两个本地计数与共享计数同步之前,它们都可能低于限制,从而允许请求超过配置的限制。
subgraph location["一个 Cloudflare 位置"]
direction TB
requests["发往一个或<br/>多个 Workers 的请求"]
requests --> a["检查本地计数 A<br/>低于限制:允许请求"]
requests --> b["检查本地计数 B<br/>低于限制:允许请求"]
a <-. "后台更新" .-> shared["此位置的<br/>共享计数"]
b <-. "后台更新" .-> shared
end
其他 Cloudflare 位置会维护单独的计数。本地计数并不代表每个 Worker 都有独立配额。
例如,如果你配置了每 10 秒 30 个请求,一波请求可能导致超过 30 次 limit() 调用返回 success: true。跨 Worker 共享命名空间或等待每次调用完成,都不会使合并后的限制变为严格限制。Worker 数量不会决定可超出限制的请求数。
如果需要在所有位置实施单一严格限制,请使用 Durable Objects实现速率限制器。
如需针对每个凭据实施上游 API 配额,请将该凭据的请求路由到同一个 Durable Object。在允许请求前,一起检查并更新其计数器,并将计数器持久化到 Durable Object 存储中。每个凭据使用单独的对象。
根据上游 API 的速率限制规则设置限流器,并处理该 API 返回的 HTTP 429 响应。
速率限制绑定目前在 Cloudflare 仪表板中不可见。要从 Worker 监控被速率限制的请求:
- Workers Observability — 使用 Workers Logs 和 Traces 观察 Worker 在超出速率限制时返回的 HTTP 429 响应。
- Workers Analytics Engine — 向 Worker 添加 Analytics Engine 绑定,并在
limit()返回{ success: false }时发出自定义数据点(例如rate_limited事件)。这允许您构建仪表板并随时间查询速率限制指标。
@elithrar/workers-hono-rate-limit↗ — 中间件,让您轻松为 Hono ↗ 应用程序中的路由添加速率限制。@hono-rate-limiter/cloudflare↗ — 中间件,让您轻松为 Hono ↗ 应用程序中的路由添加速率限制,并提供多种数据存储供选择。hono-cf-rate-limit↗ — 用于 Hono 应用程序的中间件,在 Cloudflare Workers 中应用速率限制,由 Wrangler 的内置功能提供支持。