Documentation
¶
Index ¶
- Variables
- func GetRateLimitStats() map[string]RateLimitStats
- func HTTPClientMiddleware(rl *RateLimitMiddleware) func(http.RoundTripper) http.RoundTripper
- func HTTPMiddleware(rl *RateLimitMiddleware) func(http.Handler) http.Handler
- func HTTPWaitMiddleware(rl *RateLimitMiddleware) func(http.Handler) http.Handler
- func IsGRPCRateLimitError(err error) bool
- func IsHTTPRateLimitError(err error) bool
- func IsRateLimitError(err error) bool
- func OptionalRateLimit(rl *RateLimitMiddleware) func(http.Handler) http.Handler
- func RateLimitInfo(rl *RateLimitMiddleware) func(http.Handler) http.Handler
- func RequireRateLimit(rl *RateLimitMiddleware) func(http.Handler) http.Handler
- func ResetAllRateLimitStats()
- func ResetRateLimitStats(name string) bool
- func StreamClientInterceptor(rl *RateLimitMiddleware) grpc.StreamClientInterceptor
- func StreamServerInterceptor(rl *RateLimitMiddleware) grpc.StreamServerInterceptor
- func UnaryClientInterceptor(rl *RateLimitMiddleware) grpc.UnaryClientInterceptor
- func UnaryServerInterceptor(rl *RateLimitMiddleware) grpc.UnaryServerInterceptor
- func UnaryServerWaitInterceptor(rl *RateLimitMiddleware) grpc.UnaryServerInterceptor
- func UpdateRateLimit(name string, newRate float64, newBurst int) bool
- type CallbackKeyExtractor
- type ChainKeyExtractor
- type CompositeKeyExtractor
- type Config
- type HashKeyExtractor
- type HeaderKeyExtractor
- type IPKeyExtractor
- type KeyExtractor
- type Limiter
- type Manager
- func (m *Manager) Get(name string) (*RateLimitMiddleware, bool)
- func (m *Manager) GetOrCreate(name string, rate ...float64) *RateLimitMiddleware
- func (m *Manager) List() []string
- func (m *Manager) Remove(name string) bool
- func (m *Manager) ResetStats()
- func (m *Manager) ResetStatsByName(name string) bool
- func (m *Manager) Stats() map[string]RateLimitStats
- func (m *Manager) UpdateRate(name string, newRate float64, newBurst int) bool
- type ManagerConfig
- type PathKeyExtractor
- type RateLimitMiddleware
- func (rl *RateLimitMiddleware) Allow(ctx context.Context, metadata map[string]any) error
- func (rl *RateLimitMiddleware) Burst() int
- func (rl *RateLimitMiddleware) ClearLimiters()
- func (rl *RateLimitMiddleware) GetActiveLimiters() []string
- func (rl *RateLimitMiddleware) Init() context.CancelFunc
- func (rl *RateLimitMiddleware) LimitRate() float64
- func (rl *RateLimitMiddleware) Name() string
- func (rl *RateLimitMiddleware) ResetStats()
- func (rl *RateLimitMiddleware) StartGC(ctx context.Context)
- func (rl *RateLimitMiddleware) Stats() Stats
- func (rl *RateLimitMiddleware) String() string
- func (rl *RateLimitMiddleware) UpdateRate(newRate float64, newBurst int)
- func (rl *RateLimitMiddleware) Wait(ctx context.Context, metadata map[string]any) error
- type RateLimitStats
- type Stats
- type TenantKeyExtractor
- type UserKeyExtractor
Constants ¶
This section is empty.
Variables ¶
View Source
var ( // ErrRateLimitExceeded 超过限流阈值错误 ErrRateLimitExceeded = errors.New("rate limit exceeded") // ErrRateLimiterNotFound 限流器未找到错误 ErrRateLimiterNotFound = errors.New("rate limiter not found") )
Functions ¶
func GetRateLimitStats ¶
func GetRateLimitStats() map[string]RateLimitStats
GetRateLimitStats 从默认管理器获取统计信息
func HTTPClientMiddleware ¶
func HTTPClientMiddleware(rl *RateLimitMiddleware) func(http.RoundTripper) http.RoundTripper
HTTPClientMiddleware 返回 HTTP 客户端限流中间件
func HTTPMiddleware ¶
func HTTPMiddleware(rl *RateLimitMiddleware) func(http.Handler) http.Handler
HTTPMiddleware 返回 HTTP 限流中间件
func HTTPWaitMiddleware ¶
func HTTPWaitMiddleware(rl *RateLimitMiddleware) func(http.Handler) http.Handler
HTTPWaitMiddleware 返回等待型 HTTP 限流中间件（会等待而不是直接拒绝）
func IsGRPCRateLimitError ¶
IsGRPCRateLimitError 检查错误是否为 gRPC 限流相关错误
func IsHTTPRateLimitError ¶
IsHTTPRateLimitError 检查错误是否为 HTTP 限流错误
func OptionalRateLimit ¶
func OptionalRateLimit(rl *RateLimitMiddleware) func(http.Handler) http.Handler
OptionalRateLimit 创建可选限流中间件（限流失败不会阻止请求，但会记录）
func RateLimitInfo ¶
func RateLimitInfo(rl *RateLimitMiddleware) func(http.Handler) http.Handler
RateLimitInfo 限流信息中间件（添加限流状态头部）
func RequireRateLimit ¶
func RequireRateLimit(rl *RateLimitMiddleware) func(http.Handler) http.Handler
RequireRateLimit 创建需要限流检查的中间件（用于特定路由）
func ResetAllRateLimitStats ¶
func ResetAllRateLimitStats()
ResetAllRateLimitStats 重置默认管理器中的所有限流中间件统计信息
func ResetRateLimitStats ¶
ResetRateLimitStats 重置默认管理器中的限流中间件统计信息
func StreamClientInterceptor ¶
func StreamClientInterceptor(rl *RateLimitMiddleware) grpc.StreamClientInterceptor
StreamClientInterceptor 返回一个 gRPC 流客户端拦截器，用于限流
func StreamServerInterceptor ¶
func StreamServerInterceptor(rl *RateLimitMiddleware) grpc.StreamServerInterceptor
StreamServerInterceptor 返回一个 gRPC 流服务器拦截器，用于限流
func UnaryClientInterceptor ¶
func UnaryClientInterceptor(rl *RateLimitMiddleware) grpc.UnaryClientInterceptor
UnaryClientInterceptor 返回一个 gRPC 一元客户端拦截器，用于限流
func UnaryServerInterceptor ¶
func UnaryServerInterceptor(rl *RateLimitMiddleware) grpc.UnaryServerInterceptor
UnaryServerInterceptor 返回一个 gRPC 一元服务器拦截器，用于限流
func UnaryServerWaitInterceptor ¶
func UnaryServerWaitInterceptor(rl *RateLimitMiddleware) grpc.UnaryServerInterceptor
UnaryServerWaitInterceptor 返回等待型一元服务器拦截器（会等待而不是直接拒绝）
Types ¶
type CallbackKeyExtractor ¶
type CallbackKeyExtractor struct {
ExtractFunc func(ctx context.Context, metadata map[string]any) (string, error)
}
CallbackKeyExtractor 回调键提取器（允许业务方自定义提取逻辑）
func NewCallbackKeyExtractor ¶
func NewCallbackKeyExtractor(extractFunc func(ctx context.Context, metadata map[string]any) (string, error)) *CallbackKeyExtractor
NewCallbackKeyExtractor 创建回调键提取器
type ChainKeyExtractor ¶
type ChainKeyExtractor struct {
Extractors []KeyExtractor
}
ChainKeyExtractor 链式键提取器（按顺序尝试多个提取器，返回第一个成功的结果）
func NewChainKeyExtractor ¶
func NewChainKeyExtractor(extractors ...KeyExtractor) *ChainKeyExtractor
NewChainKeyExtractor 创建链式键提取器
type CompositeKeyExtractor ¶
type CompositeKeyExtractor struct {
Extractors []KeyExtractor
Separator string
Prefix string
}
CompositeKeyExtractor 复合键提取器（组合多个提取器的结果）
func NewCompositeKeyExtractor ¶
func NewCompositeKeyExtractor(separator, prefix string, extractors ...KeyExtractor) *CompositeKeyExtractor
NewCompositeKeyExtractor 创建复合键提取器
type Config ¶
type Config struct {
Name string
Rate float64
Burst int
KeyExtractor KeyExtractor
EnableMetrics bool
OnRateLimit func(ctx context.Context, key string, rate float64)
DefaultKey string
// IdleTTL 一个 key 多久没有请求后被回收，默认 10 分钟。
// 设为 0 禁用 GC（适合 key 数量固定的场景）。
IdleTTL time.Duration
// GCInterval GC 扫描间隔，默认 5 分钟。
GCInterval time.Duration
// RateOverride 按 key 查询差异化配额。返回 (rate, burst, true) 表示使用覆盖值，
// 返回 false 或未配置时使用默认 Rate/Burst。
// 典型场景：per-tenant 差异化限流，从配置/DB 读取各租户配额。
RateOverride func(key string) (rate float64, burst int, ok bool)
}
Config 限流配置
type HashKeyExtractor ¶
type HashKeyExtractor struct {
Extractor KeyExtractor
Prefix string
}
HashKeyExtractor 哈希键提取器（对提取的键进行 MD5 哈希）
func NewHashKeyExtractor ¶
func NewHashKeyExtractor(extractor KeyExtractor, prefix string) *HashKeyExtractor
NewHashKeyExtractor 创建哈希键提取器
type HeaderKeyExtractor ¶
type HeaderKeyExtractor struct {
// HeaderName Header 名称
HeaderName string
// Prefix 键前缀
Prefix string
}
HeaderKeyExtractor HTTP Header 键提取器
func NewHeaderKeyExtractor ¶
func NewHeaderKeyExtractor(headerName, prefix string) *HeaderKeyExtractor
NewHeaderKeyExtractor 创建 Header 键提取器
type IPKeyExtractor ¶
type IPKeyExtractor struct {
// UseXForwardedFor 是否使用 X-Forwarded-For 头
UseXForwardedFor bool
// UseXRealIP 是否使用 X-Real-IP 头
UseXRealIP bool
}
IPKeyExtractor IP 地址键提取器
type KeyExtractor ¶
type KeyExtractor interface {
Extract(ctx context.Context, metadata map[string]any) (string, error)
}
KeyExtractor 键提取器接口，用于从请求中提取限流键
type Limiter ¶
type Limiter interface {
Allow() bool
Wait(ctx context.Context) error
Reserve() *rate.Reservation
Limit() rate.Limit
Burst() int
}
Limiter 限流器接口
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager 限流中间件管理器
func (*Manager) GetOrCreate ¶
func (m *Manager) GetOrCreate(name string, rate ...float64) *RateLimitMiddleware
GetOrCreate 获取或创建限流中间件
func (*Manager) ResetStatsByName ¶
ResetStatsByName 重置指定名称的限流中间件统计信息
type ManagerConfig ¶
type ManagerConfig struct {
// DefaultRate 默认限流速率
DefaultRate float64
// DefaultBurst 默认突发容量
DefaultBurst int
// DefaultKeyExtractor 默认键提取器
DefaultKeyExtractor KeyExtractor
// EnableLogging 是否启用日志
EnableLogging bool
// EnableMetrics 是否启用指标统计
EnableMetrics bool
}
ManagerConfig 管理器配置
type PathKeyExtractor ¶
PathKeyExtractor 路径键提取器
func NewPathKeyExtractor ¶
func NewPathKeyExtractor(prefix string, stripQuery bool) *PathKeyExtractor
NewPathKeyExtractor 创建路径键提取器
type RateLimitMiddleware ¶
type RateLimitMiddleware struct {
// contains filtered or unexported fields
}
RateLimitMiddleware 限流中间件
func GetRateLimitMiddleware ¶
func GetRateLimitMiddleware(name string, rate ...float64) *RateLimitMiddleware
GetRateLimitMiddleware 从默认管理器获取或创建限流中间件
func NewRateLimitMiddleware ¶
func NewRateLimitMiddleware(config Config) *RateLimitMiddleware
NewRateLimitMiddleware 创建限流中间件。 GC 不会自动启动——将返回值传给 beauty.WithComponent 可接入框架生命周期自动启停； 也可手动调用 StartGC(ctx)。
func (*RateLimitMiddleware) ClearLimiters ¶
func (rl *RateLimitMiddleware) ClearLimiters()
ClearLimiters 立即清空所有 limiter（释放内存）
func (*RateLimitMiddleware) GetActiveLimiters ¶
func (rl *RateLimitMiddleware) GetActiveLimiters() []string
GetActiveLimiters 返回当前所有活跃 key 列表
func (*RateLimitMiddleware) Init ¶
func (rl *RateLimitMiddleware) Init() context.CancelFunc
Init 实现 core.Component 接口，启动后台 GC goroutine。 Name() 已在上方声明，两个方法合起来满足 core.Component 接口。 通过 beauty.WithComponent(rl) 接入框架后，GC 随应用启动/停止自动管理，无需手动调用 StartGC。
用法：
rl := ratelimit.NewRateLimitMiddleware(cfg)
app := beauty.New(
beauty.WithComponent(rl), // 自动启停 GC
beauty.WithWebServer(":8080", mux,
webserver.WithMiddleware(ratelimit.HTTPMiddleware(rl)),
),
)
func (*RateLimitMiddleware) LimitRate ¶
func (rl *RateLimitMiddleware) LimitRate() float64
LimitRate 返回限流率
func (*RateLimitMiddleware) ResetStats ¶
func (rl *RateLimitMiddleware) ResetStats()
ResetStats 重置统计信息
func (*RateLimitMiddleware) StartGC ¶
func (rl *RateLimitMiddleware) StartGC(ctx context.Context)
StartGC 启动后台 GC，ctx 取消时停止。 通常在应用启动时调用一次；若 IdleTTL == 0 则为空操作。
func (*RateLimitMiddleware) String ¶
func (rl *RateLimitMiddleware) String() string
func (*RateLimitMiddleware) UpdateRate ¶
func (rl *RateLimitMiddleware) UpdateRate(newRate float64, newBurst int)
UpdateRate 运行时更新限流参数，同时刷新所有已存在的 limiter。
type RateLimitStats ¶
type RateLimitStats struct {
Name string `json:"name"`
Rate float64 `json:"rate"`
Burst int `json:"burst"`
Stats Stats `json:"stats"`
ActiveLimiters []string `json:"active_limiters"`
}
RateLimitStats 限流统计信息
type Stats ¶
type Stats struct {
TotalRequests uint64 `json:"total_requests"`
AllowedRequests uint64 `json:"allowed_requests"`
LimitedRequests uint64 `json:"limited_requests"`
ActiveLimiters int `json:"active_limiters"`
LimiterStats map[string]uint64 `json:"limiter_stats"`
LastLimitTime time.Time `json:"last_limit_time"`
}
Stats 限流统计信息
type TenantKeyExtractor ¶ added in v0.8.0
type TenantKeyExtractor struct {
Prefix string
}
TenantKeyExtractor 租户键提取器。 优先从 tenant.FromContext 读取（需 tenant.HTTPMiddleware 在前）， fallback 到 Header X-Tenant-ID。
func NewTenantKeyExtractor ¶ added in v0.8.0
func NewTenantKeyExtractor() *TenantKeyExtractor
NewTenantKeyExtractor 创建租户键提取器，默认 prefix 为 "tenant"。
type UserKeyExtractor ¶
type UserKeyExtractor struct {
// UserIDKey 用户ID在元数据中的键名
UserIDKey string
}
UserKeyExtractor 用户键提取器（基于用户ID）
func NewUserKeyExtractor ¶
func NewUserKeyExtractor(userIDKey string) *UserKeyExtractor
NewUserKeyExtractor 创建用户键提取器
Source Files
Click to show internal directories.
Click to hide internal directories.