Documentation
¶
Overview ¶
Package ratelimit 提供基于键的限流原语:令牌桶 + 滑动窗口两种实现, 外加 HTTP 中间件,可与 pkg/handler 组合(声明式 WithRatelimit)。
设计要点(per-user 限流 + 通用 token bucket):
- Limiter 接口:Allow(key) (allowed, retryAfter),按 key 隔离(如按 userID / IP);
- TokenBucket:固定速率补令牌,允许突发;无锁化设计用 sync.Map + 互斥桶;
- SlidingWindow:滑动窗口(精确),用时间戳 deque;
- HTTP middleware:超限返回 429 + Retry-After 头;
- 后台 gc:清理长时间无活动的 key,避免内存泄漏(参考 pkg/token 的 gc 模式)。
零值不可用,用 New 构造。Limiter 并发安全;Stop 后 gc goroutine 退出。
Index ¶
- func ClientIP(r *http.Request) string
- func Middleware(l Limiter, keyFn KeyFunc) func(http.Handler) http.Handler
- func MiddlewareWithLimiter(l Limiter, keyFn KeyFunc) func(http.Handler) http.Handler
- func WithLimiter(ctx context.Context, l Limiter) context.Context
- type KeyFunc
- type Limiter
- type Option
- type SlidingWindow
- type TokenBucket
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Middleware ¶
Middleware 返回 HTTP 限流中间件:keyFn 提取 key,limiter 限流。 超限返回 429 + Retry-After 头(秒级)。keyFn 返回空串则跳过限流。
func MiddlewareWithLimiter ¶
MiddlewareWithLimiter 返回带 limiter 注入 ctx 的中间件:下游 handler 可用 FromContext 取 limiter 做更细粒度限流(如对某资源再限一次)。
Types ¶
type Limiter ¶
Limiter 限流器接口。按 key 隔离(每个 key 独立计数)。 返回 (allowed, retryAfter):retryAfter=0 表示立即可重试或已放行。
func FromContext ¶
FromContext 从 ctx 取出 Limiter(没有则 nil)。
type Option ¶
type Option func(*config)
Option 配置限流器。
func WithGcInterval ¶
WithGcInterval 设置 gc 扫描间隔。默认 1min。
func WithMaxIdle ¶
WithMaxIdle 设置 key 最大空闲时长(超过则被 gc 回收)。默认 5min。
type SlidingWindow ¶
type SlidingWindow struct {
// contains filtered or unexported fields
}
SlidingWindow 滑动窗口限流器:在 window 时长内最多 limit 次请求,精确计数。
func NewSlidingWindow ¶
func NewSlidingWindow(limit int, window time.Duration, opts ...Option) *SlidingWindow
NewSlidingWindow 创建滑动窗口限流器。limit<=0 或 window<=0 视为不限。
func (*SlidingWindow) Allow ¶
func (sw *SlidingWindow) Allow(key string) (bool, time.Duration)
Allow 按 key 限流。滑动窗口:清除早于 window 的旧记录后判断数量。
func (*SlidingWindow) String ¶
func (sw *SlidingWindow) String() string
type TokenBucket ¶
type TokenBucket struct {
// contains filtered or unexported fields
}
TokenBucket 令牌桶限流器:固定速率补令牌,允许突发(初始满桶)。 burst 为桶容量(最大突发数),rate 为每秒补充令牌数。
func NewTokenBucket ¶
func NewTokenBucket(burst int, rate float64, opts ...Option) *TokenBucket
NewTokenBucket 创建令牌桶限流器。burst<=0 或 rate<=0 视为不限(Allow 永远 true)。 gc 每 gcInterval 清理一次超过 maxIdle 无活动的 key。
Source Files