starlette 本身不包含内置的全局限流中间件,实现请求频率限制的标准做法是引入第三方库 slowapi。该库基于 flask-limiter 开发,通过装饰器或中间件形式集成到 starlette 应用中,默认使用内存作为存储后端,支持 ip、用户 id 等策略。

如何配置并应用限流中间件
在 Starlette 中集成 slowapi 需要实例化 SlowAPIMiddleware 并将其添加到应用栈中。核心步骤包括创建 RateLimiter 对象、定义路由以及使用 @limiter.limit() 装饰器指定限制规则。例如,限制特定接口每秒最多处理 5 次请求,超出后将返回 429 Too Many Requests 状态码。

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address
from slowapi.errors import RateLimitExceeded
# 1. 初始化限流器
limiter = Limiter(key_func=get_remote_address)
app = Starlette()
app.state.limiter = limiter
# 2. 注册错误处理器
@app.exception_handler(RateLimitExceeded)
async def rate_limit_handler(request, exc):
return JSONResponse(
status_code=429,
content={"detail": "Rate limit exceeded"}
)
# 3. 应用限流装饰器
@app.get("/data")
@limiter.limit("5 per second")
async def get_data(request):
return JSONResponse({"status": "ok"})
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
上述代码展示了完整的集成流程。首先导入必要的组件,包括 Limiter 和获取客户端地址的工具函数 get_remote_address。接着在 app.state 中挂载限流器实例,这是 slowapi 识别上下文的关键。然后注册异常处理器以自定义 429 错误的响应格式。最后在路由函数上添加 @limiter.limit("5 per second") 装饰器,明确限制策略。运行该程序后,同一 IP 在 1 秒内发起第 6 个请求时,将收到包含详细信息的 JSON 响应。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。
如何自定义限流键值与存储后端
默认情况下,slowapi 使用内存字典存储计数,重启服务后数据丢失。若需持久化或分布式共享状态,可替换为 Redis 存储。同时,可以通过自定义 key_func 来改变限流的维度,例如基于 API Key 或用户 ID 进行限制,而非仅依赖 IP 地址。

import redis
from slowapi import Limiter
from slowapi.util import get_remote_address
from starlette.requests import Request
# 1. 连接 Redis
redis_client = redis.Redis(host='localhost', port=6379, db=0)
# 2. 自定义 key_func:基于 Header 中的 API Key
def get_api_key(request: Request) -> str:
api_key = request.headers.get("X-API-Key")
return api_key if api_key else get_remote_address(request)
# 3. 初始化 Limiter 使用 Redis
limiter = Limiter(
key_func=get_api_key,
storage_uri="redis://localhost:6379",
default_limits=["100 per hour"]
)
# 后续路由逻辑同上...
此示例演示了如何切换存储后端并细化限流粒度。通过传入 storage_uri="redis://...",限流计数器将持久化至 Redis,支持多实例部署。自定义的 get_api_key 函数优先读取请求头中的 X-API-Key,若不存在则回退到 IP 地址。这种机制允许对认证用户实施更宽松或更严格的配额管理。注意,使用 Redis 存储时需确保网络连通性及密钥安全性,且 slowapi 会自动处理 Redis 连接的序列化与过期时间设置。
当触发限流时中间件返回的具体 HTTP 状态码是什么
当请求超过设定的速率限制时,slowapi 会抛出 RateLimitExceeded 异常,默认情况下 Starlette 会将其转换为 HTTP 429 Too Many Requests 状态码。开发者可以通过注册自定义异常处理器来修改返回的内容结构,但状态码保持为 429 以符合 RFC 标准。

















