Webman限流中间件需正确挂载位置、选用合适驱动并保障原子性，否则无效；应选全局/路由组/单个路由中恰当位置，优先tinywan/limit-traffic以确保Redis原子操作与标准响应头。
Webman 限流中间件不是装完包就自动生效的——挂错位置、配错驱动、漏掉原子性保障，都会让限流形同虚设。真正起作用的，是中间件注册时机、Redis 操作方式、以及 key 的设计逻辑。
中间件该挂在哪：全局、路由组还是单个路由？
挂载位置直接决定它能不能拦住请求：
- 全局中间件（
config/middleware.php中''键下）会拦截所有请求，包括/static/、/favicon.ico—— 若没排除静态资源路径，图片和 JS 文件也会被计数，容易误触阈值 - 路由组中间件（
Route::group('/api', function () { ... })->middleware([...])）只对组内子路由生效，但 Webman 1.0.12+ 才支持该写法；旧版本必须每个子路由单独调用->middleware()，否则不执行 - 单个路由中间件（如
Route::get('/user', ...)->middleware([...])）可用，但无法复用；若多个接口策略一致，硬编码易维护错
tinywan/limit-traffic 和 webman/rate-limiter 怎么选？
两者都支持 Redis/Apcu/Memory，但底层行为差异大，选错会漏控或误拒：
-
tinywan/limit-traffic默认用 Lua 脚本封装INCR+EXPIRE，保证 Redis 原子性，高并发下不会超限；自动注入X-Rate-Limit-Limit、X-Rate-Limit-Remaining等标准响应头，适合依赖前端读取X-Rate-Limit-Reset做退避重试的场景 -
webman/rate-limiter从 1.1.0 版本起才默认启用 Lua 原子操作；原生支持@RateLimiter注解，可直接在控制器方法上写@RateLimiter(limit=5, period=60)，适合按updateProfile()这类方法级精细控制，但需手动处理响应头与 429 异常 - 若你用的是 Webman webman/rate-limiter 的
INCR+EXPIRE组合非原子，两个请求同时读到 99、各自INCR到 100，结果变成 101 —— 这就是“超卖”问题
Redis key 怎么设计才不串号？
key 不带客户端标识或时间窗口，就会导致多个用户共用一个计数器，或同一用户调不同接口被误限：
立即学习“PHP免费学习笔记（深入）”；
- 推荐格式：
rate_limit:{ip}:{route}:{timestamp}，其中{timestamp}取分钟级时间戳（floor(time() / 60)），避免滑动窗口精度缺失 - 如果按用户限流，别只用
$request->ip()—— Nginx + PHP-FPM 架构下它常是127.0.0.1；应改用$request->header('x-real-ip')或$request->header('x-forwarded-for') - 别用
SETNX+INCR模拟原子操作：竞态条件下可能漏计数；Cache::inc()在 ThinkPHP 里本质是INCR，但 Webman 生态中请确认 Redis 驱动版本 ≥ 6.0.12（旧版有并发 bug）
触发限流后返回什么才算合规？
状态码和响应头不对，前端就无法识别“暂时不可用”，退避重试逻辑会失效：
- HTTP 状态码必须是
429 Too Many Requests，不是403或503 - 响应头必须包含：
X-Rate-Limit-Limit（窗口最大请求数）、X-Rate-Limit-Remaining（剩余次数）、X-Rate-Limit-Reset（重置秒数），否则前端拿不到重试依据 - 响应体建议精简 JSON：
{"code":429,"msg":"Too many requests"}；别返回 HTML 或大段提示，尤其在 API 场景下 - Webman 中间件返回值必须是
Webman\Http\Response实例，不能是字符串或json()调用结果（除非已封装为 Response）；漏掉$next($request)或返回类型错误，会导致流程中断且无报错
真正难的不是写限流逻辑，而是确保每次请求都被同一个 key 计数、每次计数都在原子上下文中完成、每次拒绝都返回可被客户端解析的标准信号——这三个点漏掉任何一个，限流就只是心理安慰。
