ratelimit

Documentation

Overview

Package ratelimit 提供限流功能 支持内存和 Redis 两种存储方式，适用于单机和分布式场景

Package ratelimit 提供限流功能 本文件实现基于 Redis 的分布式限流器

Package ratelimit 限流统计类型定义

Index

• type KeyStats
• type Limiter
• type LimiterStats
• type MemoryLimiter
  • func NewMemoryLimiter(cleanupInterval time.Duration) *MemoryLimiter
  • func (ml *MemoryLimiter) Allow(ctx context.Context, key string, ratePerSecond int, burst int) (bool, error)
  • func (ml *MemoryLimiter) Close() error
  • func (ml *MemoryLimiter) DetailedStats() *LimiterStats
  • func (ml *MemoryLimiter) Stats() map[string]interface{}
• type RedisLimiter
  • func NewRedisLimiter(client redis.UniversalClient, keyPrefix string) *RedisLimiter
  • func (rl *RedisLimiter) Allow(ctx context.Context, key string, ratePerSecond int, burst int) (bool, error)
  • func (rl *RedisLimiter) AllowTokenBucket(ctx context.Context, key string, ratePerSecond int, burst int) (bool, error)
  • func (rl *RedisLimiter) Close() error
  • func (rl *RedisLimiter) DetailedStats() *LimiterStats
  • func (rl *RedisLimiter) Stats() map[string]interface{}
• type StatsProvider

Types

type KeyStats

type KeyStats struct {
	Key      string `json:"key"`
	Allowed  int64  `json:"allowed"`
	Rejected int64  `json:"rejected"`
}

KeyStats 单个限流键的统计

type Limiter

type Limiter interface {
	// Allow 检查是否允许请求
	// key: 限流键（如 IP、用户 ID、路径等）
	// ratePerSecond: 每秒允许的请求数
	// burst: 突发容量（令牌桶大小）
	// 返回: 是否允许请求，错误信息
	Allow(ctx context.Context, key string, ratePerSecond int, burst int) (bool, error)

	// Close 关闭限流器，释放资源
	Close() error
}

Limiter 限流器接口 定义限流器的基本行为

type LimiterStats

type LimiterStats struct {
	Type          string     `json:"type"`
	TotalAllowed  int64      `json:"total_allowed"`
	TotalRejected int64      `json:"total_rejected"`
	ActiveKeys    int        `json:"active_keys"`
	TopKeys       []KeyStats `json:"top_keys"`
}

LimiterStats 限流器详细统计

type MemoryLimiter

type MemoryLimiter struct {
	// contains filtered or unexported fields
}

MemoryLimiter 内存限流器 使用 golang.org/x/time/rate 实现令牌桶算法 适用于单机部署场景

func NewMemoryLimiter

func NewMemoryLimiter(cleanupInterval time.Duration) *MemoryLimiter

NewMemoryLimiter 创建内存限流器 cleanupInterval: 清理过期条目的间隔时间

func (*MemoryLimiter) Allow

func (ml *MemoryLimiter) Allow(ctx context.Context, key string, ratePerSecond int, burst int) (bool, error)

Allow 检查是否允许请求

func (*MemoryLimiter) Close

func (ml *MemoryLimiter) Close() error

Close 关闭限流器

func (*MemoryLimiter) DetailedStats

func (ml *MemoryLimiter) DetailedStats() *LimiterStats

DetailedStats 获取详细限流统计

func (*MemoryLimiter) Stats

func (ml *MemoryLimiter) Stats() map[string]interface{}

Stats 获取当前限流器统计信息

type RedisLimiter

type RedisLimiter struct {
	// contains filtered or unexported fields
}

RedisLimiter Redis 限流器 使用滑动窗口算法实现分布式限流 适用于集群部署场景

func NewRedisLimiter

func NewRedisLimiter(client redis.UniversalClient, keyPrefix string) *RedisLimiter

NewRedisLimiter 创建 Redis 限流器 client: Redis 客户端 keyPrefix: 限流键前缀，用于区分不同应用

func (*RedisLimiter) Allow

func (rl *RedisLimiter) Allow(ctx context.Context, key string, ratePerSecond int, burst int) (bool, error)

Allow 使用滑动窗口算法检查请求是否被允许。

算法原理：

1. 以 Redis Sorted Set 存储请求记录，score 为请求时间戳（毫秒）
2. 每次请求先移除窗口（1 秒）外的旧记录
3. 统计窗口内的请求数，若未超过限制则写入新记录并放行

当 burst > ratePerSecond 时，使用 burst 作为窗口内的请求数上限， 从而允许短时间内的突发流量。

参数：

• ctx: 上下文，支持超时取消
• key: 限流键
• ratePerSecond: 每秒允许的请求数
• burst: 突发容量上限

func (*RedisLimiter) AllowTokenBucket

func (rl *RedisLimiter) AllowTokenBucket(ctx context.Context, key string, ratePerSecond int, burst int) (bool, error)

AllowTokenBucket 使用令牌桶算法检查请求是否被允许。

算法原理：

1. 以 Redis Hash 存储桶状态（当前令牌数 tokens 和上次更新时间 last_time）
2. 每次请求按 elapsed * rate 补充令牌，令牌数上限为 burst
3. 令牌充足（>= 1）时消耗一个令牌并放行，否则拒绝

与滑动窗口的区别：令牌桶天然支持突发流量——桶满时可瞬间消耗 burst 个令牌， 之后按 ratePerSecond 匀速恢复，适合对突发流量更宽容的场景。

参数：

• ctx: 上下文，支持超时取消
• key: 限流键（自动添加 "tb:" 前缀与滑动窗口的键隔离）
• ratePerSecond: 每秒令牌恢复速率
• burst: 令牌桶容量上限

func (*RedisLimiter) Close

func (rl *RedisLimiter) Close() error

Close 关闭限流器

func (*RedisLimiter) DetailedStats

func (rl *RedisLimiter) DetailedStats() *LimiterStats

DetailedStats 获取详细限流统计

func (*RedisLimiter) Stats

func (rl *RedisLimiter) Stats() map[string]interface{}

Stats 获取限流器统计信息

type StatsProvider

type StatsProvider interface {
	DetailedStats() *LimiterStats
}

StatsProvider 限流统计接口 实现此接口的限流器可以提供详细的请求统计信息