Documentation
¶
Overview ¶
Package middleware 提供 ginx 内置的 HTTP 中间件实现。
包含请求 ID 生成、跨域处理、请求超时、Panic 捕获、参数校验和 IP 限流等 6 个工业级中间件。 所有中间件通过 Manager 统一管理，支持禁用、覆盖和外部替换。
Index ¶
- func CORS(cfg CORSConfig) gin.HandlerFunc
- func RateLimit(rl *RateLimiter) gin.HandlerFunc
- func Recovery() gin.HandlerFunc
- func RequestID() gin.HandlerFunc
- func Timeout(timeout time.Duration) gin.HandlerFunc
- func Validation() gin.HandlerFunc
- type CORSConfig
- type Manager
- func (m *Manager) Append(handler ...gin.HandlerFunc)
- func (m *Manager) Build(ctx context.Context) []gin.HandlerFunc
- func (m *Manager) Disable(mt ...string)
- func (m *Manager) DisableRateLimit()
- func (m *Manager) Enable(mt ...string)
- func (m *Manager) EnableRateLimit(handler gin.HandlerFunc)
- func (m *Manager) Override(mt string, handler gin.HandlerFunc)
- func (m *Manager) RegisterBuiltin(key string, handler gin.HandlerFunc)
- type RateLimiter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CORS ¶
func CORS(cfg CORSConfig) gin.HandlerFunc
CORS 返回一个 CORS 跨域处理中间件。
根据配置自动设置 CORS 响应头，处理 OPTIONS 预检请求。 若请求 Origin 不在允许列表中，返回 403。
func RateLimit ¶
func RateLimit(rl *RateLimiter) gin.HandlerFunc
RateLimit 返回一个 IP 令牌桶限流中间件。
超限返回标准化 429 响应，白名单 IP/CIDR 直接放行。
func Recovery ¶
func Recovery() gin.HandlerFunc
Recovery 返回一个 Panic 捕获中间件。
这是组件库中唯一调用 recover() 的位置。 当 handler 中发生 panic 时，Recovery 捕获并记录调用栈， 向客户端返回标准化 500 响应。
func RequestID ¶
func RequestID() gin.HandlerFunc
RequestID 返回一个请求 ID 生成中间件。
优先使用请求头 X-Request-ID 的值，若不存在则生成 UUID v4。 生成的 ID 写入 gin.Context 的 "requestId" 键和响应头 X-Request-ID。
func Timeout ¶
func Timeout(timeout time.Duration) gin.HandlerFunc
Timeout 返回一个请求超时中间件。
向请求注入带超时的 Context，下游 Handler 应响应 ctx.Done() 以提前退出。 超时后 Handler 的写入被丢弃，并返回 503 响应。 若 timeout <= 0，则中间件不执行任何操作，直接放行。
与旧版不同：不再将 c.Next() 放入 goroutine，避免 *gin.Context 的 data race 和 sync.Pool 污染问题。
func Validation ¶
func Validation() gin.HandlerFunc
Validation 返回一个请求参数校验中间件。
校验 Content-Type 是否为 JSON、Content-Length 是否合理。 校验失败返回标准化 400 响应。
Types ¶
type CORSConfig ¶
type CORSConfig struct {
// AllowedOrigins 允许的来源列表，"*" 表示允许所有来源。
AllowedOrigins []string
// AllowedMethods 允许的 HTTP 方法列表。
AllowedMethods []string
// AllowedHeaders 允许的请求头列表。
AllowedHeaders []string
// MaxAge 预检请求缓存时间（秒）。
MaxAge int
}
CORSConfig 定义 CORS 中间件的配置参数。
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager 管理内置中间件的注册表、执行顺序和启用状态。
调用方通过 Server 的方法间接操作 Manager，不直接使用此类型。
func NewManager ¶
func NewManager() *Manager
NewManager 创建一个新的中间件管理器。
默认启用全部 6 个内置中间件（RateLimit 注册但默认禁用）。
func (*Manager) Append ¶
func (m *Manager) Append(handler ...gin.HandlerFunc)
Append 追加外部全局中间件到中间件链的末尾（路由专属中间件之前）。
func (*Manager) Build ¶
func (m *Manager) Build(ctx context.Context) []gin.HandlerFunc
Build 构建最终执行的中间件链。
按照注册顺序返回已过滤（跳过禁用项、使用覆盖项）的 HandlerFunc 列表。 返回顺序：内置（启用）→ 外部全局 → 可用于路由专属。
func (*Manager) DisableRateLimit ¶
func (m *Manager) DisableRateLimit()
DisableRateLimit 禁用限流中间件并移除其 Handler。
func (*Manager) Enable ¶
Enable 启用指定类型的内置中间件。
注意：RateLimit 中间件必须通过 EnableRateLimit 激活， 仅调用 Enable 对其无效。
func (*Manager) EnableRateLimit ¶
func (m *Manager) EnableRateLimit(handler gin.HandlerFunc)
EnableRateLimit 启用限流中间件并注册其 Handler。
func (*Manager) Override ¶
func (m *Manager) Override(mt string, handler gin.HandlerFunc)
Override 覆盖指定类型的内置中间件，使用调用方提供的自定义 Handler。
func (*Manager) RegisterBuiltin ¶
func (m *Manager) RegisterBuiltin(key string, handler gin.HandlerFunc)
RegisterBuiltin 注册一个内置中间件到管理器。
key 为中间件类型字符串，如 "request_id"、"cors" 等。 handler 为中间件工厂函数返回的 gin.HandlerFunc。
type RateLimiter ¶
type RateLimiter struct {
// contains filtered or unexported fields
}
RateLimiter 实现基于 IP 的令牌桶限流。
func NewRateLimiter ¶
func NewRateLimiter(qps int, window time.Duration, whitelistCIDRs []string) *RateLimiter
NewRateLimiter 创建一个新的 IP 限流器。
qps 为每秒允许的请求数，window 为限流窗口，whitelist 为白名单 CIDR 列表。
func (*RateLimiter) Cleanup ¶
func (rl *RateLimiter) Cleanup(interval time.Duration)
Cleanup 清理过期的桶。
Source Files