middleware

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 27, 2026 License: MIT Imports: 5 Imported by: 0

README

middleware — 网关中间件

提供 HTTP API 网关层能力:限流(Rate Limiter)、安全防护(CORS、Helmet、IP 黑白名单)与中间件链组合。

组件概览

组件 说明
RateLimiter 基于 API Key 的分钟/日/突发三维限流
SlidingWindowLimiter 滑动窗口限流器
TokenBucketLimiter 令牌桶限流器
SecurityMiddleware CORS + Helmet + IP 黑白名单
GatewayMiddleware 集成限流、鉴权、日志、指标、追踪的统一网关链
MiddlewareChain 通用中间件链 Builder

快速开始

限流器
import "github.com/leeforge/framework/middleware"

backend := middleware.NewRedisBackend()
rateLimiter := middleware.NewRateLimiter(backend, middleware.RateLimitConfig{
    DefaultRate:  100, // 每分钟 100 次
    DefaultDaily: 1000, // 每天 1000 次
    Burst:        10,  // 突发 10 次/秒
    Strategies: map[string]middleware.Strategy{
        "/api/upload": {Rate: 10, Daily: 100, Burst: 2}, // 上传接口单独限流
    },
})

r.Use(rateLimiter.Middleware)
安全中间件
security := middleware.NewSecurityMiddleware(middleware.SecurityConfig{
    CORS: middleware.CORSConfig{
        Enabled:        true,
        AllowedOrigins: []string{"https://myapp.com"},
        AllowedMethods: []string{"GET", "POST", "PUT", "DELETE"},
        AllowedHeaders: []string{"Authorization", "Content-Type"},
        AllowCredentials: true,
        MaxAge:         86400,
    },
    Helmet:      true, // 注入安全响应头
    IPBlacklist: []string{"1.2.3.4"},
    RequestSize: 10 * 1024 * 1024, // 10MB 请求体限制
})

r.Use(security.Middleware)
网关 Builder
gw, err := middleware.NewGatewayBuilder(logger).
    WithRateLimit(middleware.RateLimitConfig{DefaultRate: 200}).
    WithAuth(true).
    WithMetrics(true).
    WithTracing(true).
    Build()

handler, _ := gw.Handler(r)
中间件链
chain := middleware.NewMiddlewareChain().
    Use(loggingMiddleware).
    Use(authMiddleware).
    Use(metricsMiddleware)

http.ListenAndServe(":8080", chain.Then(handler))

限流管理 API

// 注册管理路由(需要鉴权保护)
mux.HandleFunc("/admin/rate-limit/usage", rateLimitHandler.GetUsage)
mux.HandleFunc("/admin/rate-limit/reset", rateLimitHandler.ResetUsage)
接口 说明
GET /admin/rate-limit/usage?api_key=xxx 查看 API Key 的使用量
GET /admin/rate-limit/reset?api_key=xxx 重置 API Key 的限流计数

网关中间件执行顺序

请求 → Metrics → Tracing → Auth → RateLimit → Logging → Handler

注意事项

  • BackendAdapterRedisBackend 当前为内存模拟实现,生产环境需替换为真实 Redis 实现
  • IP 黑白名单的 IP 匹配使用字符串精确匹配(不支持 CIDR 段),需要 CIDR 时需自行扩展
  • Helmet 安全头包含:X-Content-Type-OptionsX-Frame-OptionsStrict-Transport-Security

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterRateLimitRoutes

func RegisterRateLimitRoutes(mux *http.ServeMux, handler *RateLimitHandler)

RegisterRateLimitRoutes 注册限流管理路由

Types

type AuthMiddleware

type AuthMiddleware interface {
	Middleware(next http.Handler) http.Handler
}

type BackendAdapter

type BackendAdapter interface {
	CheckLimit(key string, limit int, window int64) (bool, error)
	Increment(key string, window int64) error
	GetUsage(key string) (int, error)
	Reset(key string) error
}

BackendAdapter 限流后端适配器

type CORSConfig

type CORSConfig struct {
	Enabled          bool
	AllowedOrigins   []string
	AllowedMethods   []string
	AllowedHeaders   []string
	AllowCredentials bool
	MaxAge           int
}

type Field

type Field struct {
	Key   string
	Value interface{}
}

type Gateway

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

func NewGateway

func NewGateway(config GatewayConfig, logger LoggerAdapter) (*Gateway, error)

func (*Gateway) Handler

func (g *Gateway) Handler(next http.Handler) http.Handler

func (*Gateway) RegisterRoutes

func (g *Gateway) RegisterRoutes(mux *http.ServeMux)

func (*Gateway) Start

func (g *Gateway) Start(addr string) error

func (*Gateway) Stop

func (g *Gateway) Stop() error

type GatewayBuilder

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

func NewGatewayBuilder

func NewGatewayBuilder(logger LoggerAdapter) *GatewayBuilder

func (*GatewayBuilder) Build

func (b *GatewayBuilder) Build() (*Gateway, error)

func (*GatewayBuilder) Handler

func (b *GatewayBuilder) Handler(next http.Handler) (http.Handler, error)

func (*GatewayBuilder) WithAuth

func (b *GatewayBuilder) WithAuth(enabled bool) *GatewayBuilder

func (*GatewayBuilder) WithMetrics

func (b *GatewayBuilder) WithMetrics(enabled bool) *GatewayBuilder

func (*GatewayBuilder) WithMiddleware

func (b *GatewayBuilder) WithMiddleware(middleware func(http.Handler) http.Handler) *GatewayBuilder

func (*GatewayBuilder) WithRateLimit

func (b *GatewayBuilder) WithRateLimit(config RateLimitConfig) *GatewayBuilder

func (*GatewayBuilder) WithTracing

func (b *GatewayBuilder) WithTracing(enabled bool) *GatewayBuilder

type GatewayConfig

type GatewayConfig struct {
	RateLimit  RateLimitConfig
	EnableAuth bool
	LogLevel   string
	Metrics    bool
	Tracing    bool
}

type GatewayMiddleware

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

func NewGatewayMiddleware

func NewGatewayMiddleware(
	rateLimiter *RateLimiter,
	auth AuthMiddleware,
	logger LoggerAdapter,
	metrics MetricsAdapter,
	tracer TracerAdapter,
) *GatewayMiddleware

func (*GatewayMiddleware) Chain

func (g *GatewayMiddleware) Chain() func(next http.Handler) http.Handler

type LoggerAdapter

type LoggerAdapter interface {
	Info(msg string, fields ...Field)
	Error(msg string, err error, fields ...Field)
}

type MetricsAdapter

type MetricsAdapter interface {
	RecordRequest(method, path string, status int, duration float64)
	RecordError(method, path string, err error)
}

type MiddlewareChain

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

func NewMiddlewareChain

func NewMiddlewareChain() *MiddlewareChain

func (*MiddlewareChain) Then

func (c *MiddlewareChain) Then(handler http.Handler) http.Handler

func (*MiddlewareChain) Use

func (c *MiddlewareChain) Use(middleware func(http.Handler) http.Handler) *MiddlewareChain

type RateLimitConfig

type RateLimitConfig struct {
	DefaultRate  int                 // 默认每分钟请求数
	DefaultDaily int                 // 默认每日请求数
	Strategies   map[string]Strategy // 按路径配置
	Burst        int                 // 突发流量支持
}

RateLimitConfig 限流配置

type RateLimitHandler

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

RateLimitHandler 限流管理处理器

func NewRateLimitHandler

func NewRateLimitHandler(limiter *RateLimiter) *RateLimitHandler

NewRateLimitHandler 创建限流管理处理器

func (*RateLimitHandler) GetUsage

func (h *RateLimitHandler) GetUsage(w http.ResponseWriter, r *http.Request)

GetUsage 获取使用情况

func (*RateLimitHandler) ResetUsage

func (h *RateLimitHandler) ResetUsage(w http.ResponseWriter, r *http.Request)

ResetUsage 重置使用情况

type RateLimitMiddleware

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

RateLimitMiddleware 限流中间件工厂

func NewRateLimitMiddleware

func NewRateLimitMiddleware(backend BackendAdapter, config RateLimitConfig) *RateLimitMiddleware

NewRateLimitMiddleware 创建限流中间件工厂

func (*RateLimitMiddleware) Middleware

func (m *RateLimitMiddleware) Middleware(next http.Handler) http.Handler

Middleware 获取中间件

func (*RateLimitMiddleware) WithPath

func (m *RateLimitMiddleware) WithPath(path string, strategy Strategy) *RateLimitMiddleware

WithPath 针对特定路径的限流

type RateLimiter

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

RateLimiter 限流器

func NewRateLimiter

func NewRateLimiter(backend BackendAdapter, config RateLimitConfig) *RateLimiter

NewRateLimiter 创建限流器

func (*RateLimiter) GetUsage

func (rl *RateLimiter) GetUsage(apiKey string) (minute, daily, burst int, err error)

GetUsage 获取 API Key 的使用情况

func (*RateLimiter) Middleware

func (rl *RateLimiter) Middleware(next http.Handler) http.Handler

Middleware 限流中间件

func (*RateLimiter) ResetKey

func (rl *RateLimiter) ResetKey(apiKey string) error

ResetKey 重置指定 Key 的限流

type RedisBackend

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

RedisBackend Redis 后端(简化版)

func NewRedisBackend

func NewRedisBackend() *RedisBackend

NewRedisBackend 创建 Redis 后端

func (*RedisBackend) CheckLimit

func (b *RedisBackend) CheckLimit(key string, limit int, window int64) (bool, error)

CheckLimit 检查限流

func (*RedisBackend) GetUsage

func (b *RedisBackend) GetUsage(key string) (int, error)

GetUsage 获取使用量

func (*RedisBackend) Increment

func (b *RedisBackend) Increment(key string, window int64) error

Increment 增加计数

func (*RedisBackend) Reset

func (b *RedisBackend) Reset(key string) error

Reset 重置计数

type SecurityConfig

type SecurityConfig struct {
	CORS        CORSConfig
	Helmet      bool
	IPWhitelist []string
	IPBlacklist []string
	RequestSize int64
}

type SecurityMiddleware

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

func NewSecurityMiddleware

func NewSecurityMiddleware(config SecurityConfig) *SecurityMiddleware

func (*SecurityMiddleware) Middleware

func (s *SecurityMiddleware) Middleware(next http.Handler) http.Handler

type SimpleLogger

type SimpleLogger struct{}

func (*SimpleLogger) Error

func (l *SimpleLogger) Error(msg string, err error, fields ...Field)

func (*SimpleLogger) Info

func (l *SimpleLogger) Info(msg string, fields ...Field)

type SlidingWindowLimiter

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

SlidingWindowLimiter 滑动窗口限流器

func NewSlidingWindowLimiter

func NewSlidingWindowLimiter(backend BackendAdapter, window time.Duration, limit int) *SlidingWindowLimiter

NewSlidingWindowLimiter 创建滑动窗口限流器

func (*SlidingWindowLimiter) Allow

func (l *SlidingWindowLimiter) Allow(key string) (bool, error)

Allow 检查是否允许请求

type Span

type Span interface {
	SetAttribute(key string, value interface{})
	End()
}

type Strategy

type Strategy struct {
	Rate  int
	Daily int
	Burst int
}

Strategy 限流策略

type TokenBucketLimiter

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

TokenBucketLimiter 令牌桶限流器

func NewTokenBucketLimiter

func NewTokenBucketLimiter(backend BackendAdapter, capacity int, refillRate float64) *TokenBucketLimiter

NewTokenBucketLimiter 创建令牌桶限流器

func (*TokenBucketLimiter) Allow

func (l *TokenBucketLimiter) Allow(key string) (bool, error)

Allow 检查是否允许请求

func (*TokenBucketLimiter) Refill

func (l *TokenBucketLimiter) Refill(key string, tokens int) error

Refill 补充令牌(需要定时调用)

type TracerAdapter

type TracerAdapter interface {
	StartSpan(name string, attrs map[string]interface{}) Span
	EndSpan(span Span, err error)
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL