直接用 golang.org/x/time/rate 就够了，它是生产级 Token 桶限速器，封装了容量、速率、纳秒精度和并发安全；避免手写易错实现，正确使用 AllowN（非阻塞）与 WaitN（阻塞需带 context 超时），按维度用 sync.Map 管理多策略，中间件中统一覆盖所有响应路径并规范 429 响应头。
为什么直接用 golang.org/x/time/rate 就够了
Go 标准库生态里，golang.org/x/time/rate 就是基于 Token 桶实现的限速器，不是模拟、不是简化版，而是生产级可用的完整实现。它把桶容量（limit）、填充速率（burst）、时间精度（纳秒级）和并发安全都封装好了，没必要自己手写一个容易出错的版本。
常见错误是看到“Token 桶”就去搜算法原理，然后照着伪代码从零造轮子：手撸定时器、自己加锁、漏掉 AllowN 的时间窗口校验……结果性能差、竞态多、还难测。
-
rate.NewLimiter(rate.Limit(10), 5)表示：每秒最多放行 10 个请求，初始桶里有 5 个 token（允许突发） - 每次调用
limiter.Allow()相当于尝试取 1 个 token；limiter.AllowN(time.Now(), n)尝试取 n 个 - 返回
false不代表失败，只表示当前没足够 token——你要决定是阻塞等待（WaitN）、降级处理，还是直接拒绝
AllowN 和 WaitN 的行为差异必须搞清
这两个方法底层共享同一个桶状态，但对外语义完全不同，选错会导致接口响应异常或服务雪崩。
-
AllowN(t, n)是非阻塞的：立刻返回true/false，不改变 goroutine 状态。适合需要快速失败的场景（比如 API 网关直接返回 429） -
WaitN(t, n)是阻塞的：如果当前 token 不足，它会 sleep 到足够 token 到账再返回（或超时）。注意：它可能让一个请求卡住几百毫秒，而你完全没感知——除非显式传入context.WithTimeout - 误用
WaitN且没设 context 超时，会导致 HTTP handler 卡住、连接堆积、P99 延迟飙升
示例：正确带超时的等待
ctx, cancel := context.WithTimeout(r.Context(), 200*time.Millisecond)
defer cancel()
err := limiter.WaitN(ctx, 1)
if err != nil {
http.Error(w, "too many requests", http.StatusTooManyRequests)
return
}
如何给不同用户/路径配不同限速策略
单个 rate.Limiter 实例只能表达一种速率策略。真实业务中，你需要按 user_id、api_path 或 ip 分维度限速，这时得自己做映射管理，但别用全局 map + 大锁——那是性能杀手。
- 用
sync.Map存map[string]*rate.Limiter，key 是维度标识（如"user:123"），value 是对应限速器 - 每个 limiter 的
burst值建议 ≥ 1，否则首次请求就可能被拒（因为 token 填充需要时间） - 注意内存泄漏：长期存活的 key（如临时 token）没清理机制，limiter 实例会一直占内存。可加简单 TTL，比如用
time.AfterFunc定期删过期项 - 不要为每个请求新建 limiter——初始化成本低，但高频创建+丢弃会触发 GC 频繁扫描
HTTP 中间件里嵌入限速的坑点
在 Gin/Chi 等框架里写限速中间件时，最容易忽略的是「限速逻辑是否覆盖所有出口」以及「错误响应格式是否统一」。
- 别只在
HandleFunc开头调AllowN，要确保 panic、重定向、流式响应（如 SSE）等分支也受控——最好用defer或统一 response writer 包装 - 返回 429 时，务必设置
X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset头，否则前端无法友好退避 -
rate.Limiter本身不暴露剩余 token 数，得自己算：limiter.Limit()是速率，limiter.Burst()是桶大小，剩余数需结合上次调用时间估算——更稳妥的做法是用ReserveN获取*rate.Reservation，再调reservation.OK()和reservation.Delay()
真正麻烦的从来不是算法本身，而是怎么让限速器在高并发下不拖慢主流程、不掩盖真实错误、不因配置漂移突然切掉整批流量——这些细节藏在 ReserveN 的返回值检查里，藏在 context 超时的粒度里，也藏在你删不用的 limiter 时有没有 defer cancel。
