litemiddleware

litemiddleware

内置 HTTP 中间件组件，提供开箱即用的通用中间件实现。

特性

• 统一接口 - 所有中间件实现 common.IBaseMiddleware 接口
• 灵活配置 - 配置属性使用指针类型，支持可选配置和默认值覆盖
• 依赖注入 - 通过 inject:"" 标签自动注入 Manager 组件
• 执行顺序 - 预定义 Order 常量，支持自定义执行顺序
• 完整测试 - 所有中间件包含单元测试和示例

快速开始

import "github.com/lite-lake/litecore-go/component/litemiddleware"

// 使用默认配置创建中间件
recovery := litemiddleware.NewRecoveryMiddlewareWithDefaults()
reqLogger := litemiddleware.NewRequestLoggerMiddlewareWithDefaults()
cors := litemiddleware.NewCorsMiddlewareWithDefaults()
security := litemiddleware.NewSecurityHeadersMiddlewareWithDefaults()

// 注册到容器
container.RegisterMiddleware(middlewareContainer, recovery)
container.RegisterMiddleware(middlewareContainer, reqLogger)
container.RegisterMiddleware(middlewareContainer, cors)
container.RegisterMiddleware(middlewareContainer, security)

可用中间件列表

配置说明

所有中间件配置支持以下通用字段：

配置属性使用指针类型（*string, *int, *bool 等），未配置的字段将使用默认值。这种设计允许：

• 零值区分（如 false 与未配置）
• 默认值覆盖
• 可选配置

Recovery 中间件

panic 恢复中间件，捕获 panic 并记录日志，返回友好的错误响应。

配置选项

使用示例

// 使用默认配置
recovery := litemiddleware.NewRecoveryMiddlewareWithDefaults()

// 生产环境配置（不打印堆栈）
printStack := false
cfg := &litemiddleware.RecoveryConfig{
    PrintStack:      &printStack,
    CustomErrorBody: &[]bool{true}[0],
    ErrorMessage:    &[]string{"系统繁忙，请稍后重试"}[0],
    ErrorCode:       &[]string{"SYSTEM_BUSY"}[0],
}
recovery := litemiddleware.NewRecoveryMiddleware(cfg)

RequestLogger 中间件

请求日志中间件，记录请求和响应信息，支持日志级别控制和路径过滤。

配置选项

使用示例

// 使用默认配置
reqLogger := litemiddleware.NewRequestLoggerMiddlewareWithDefaults()

// 禁用 Body 记录，调整日志级别为 debug
logBody := false
successLogLevel := "debug"
cfg := &litemiddleware.RequestLoggerConfig{
    LogBody:         &logBody,
    SuccessLogLevel: &successLogLevel,
}
reqLogger := litemiddleware.NewRequestLoggerMiddleware(cfg)

CORS 中间件

跨域资源共享中间件，支持灵活的跨域配置。

配置选项

使用示例

// 使用默认配置（允许所有源）
cors := litemiddleware.NewCorsMiddlewareWithDefaults()

// 生产环境配置（仅允许特定域名）
allowOrigins := []string{"https://example.com", "https://app.example.com"}
allowCredentials := true
cfg := &litemiddleware.CorsConfig{
    AllowOrigins:     &allowOrigins,
    AllowCredentials: &allowCredentials,
}
cors := litemiddleware.NewCorsMiddleware(cfg)

SecurityHeaders 中间件

安全头中间件，自动添加常见的安全 HTTP 头。

配置选项

使用示例

// 使用默认配置
security := litemiddleware.NewSecurityHeadersMiddlewareWithDefaults()

// 添加 CSP 和 HSTS
csp := "default-src 'self'; script-src 'self'"
hsts := "max-age=31536000; includeSubDomains"
cfg := &litemiddleware.SecurityHeadersConfig{
    ContentSecurityPolicy:   &csp,
    StrictTransportSecurity: &hsts,
}
security := litemiddleware.NewSecurityHeadersMiddleware(cfg)

RateLimiter 中间件

限流中间件，基于时间窗口的请求频率控制，支持多种限流策略。

配置选项

使用示例

// 使用默认配置（按 IP 限流，每分钟 100 次请求）
limiter := litemiddleware.NewRateLimiterMiddlewareWithDefaults()

// 按用户 ID 限流，自定义跳过条件
limit := 10
window := time.Minute
keyPrefix := "user"
cfg := &litemiddleware.RateLimiterConfig{
    Limit:     &limit,
    Window:    &window,
    KeyPrefix: &keyPrefix,
    KeyFunc: func(c *gin.Context) string {
        if userID, exists := c.Get("user_id"); exists {
            return userID.(string)
        }
        return c.ClientIP()
    },
    SkipFunc: func(c *gin.Context) bool {
        return c.GetHeader("X-Internal") == "true"
    },
}
limiter := litemiddleware.NewRateLimiterMiddleware(cfg)

响应头

Telemetry 中间件

遥测中间件，集成 OpenTelemetry 进行链路追踪和指标采集。

配置选项

使用示例

// 使用默认配置（依赖注入 TelemetryManager）
telemetry := litemiddleware.NewTelemetryMiddlewareWithDefaults()

执行顺序

预定义的中间件执行顺序（按 Order 值从小到大）：

业务自定义中间件建议从 Order 350 开始。

依赖注入

中间件通过依赖注入获取 Manager 组件：

type requestLoggerMiddleware struct {
    LoggerMgr loggermgr.ILoggerManager `inject:""`
    cfg       *RequestLoggerConfig
}

type rateLimiterMiddleware struct {
    LimiterMgr limitermgr.ILimiterManager `inject:""`
    LoggerMgr  loggermgr.ILoggerManager   `inject:""`
    config     *RateLimiterConfig
}

type telemetryMiddleware struct {
    TelemetryManager telemetrymgr.ITelemetryManager `inject:""`
    cfg              *TelemetryConfig
}

API

配置结构

RecoveryConfig

panic 恢复中间件配置

type RecoveryConfig struct {
    Name            *string // 中间件名称
    Order           *int    // 执行顺序
    PrintStack      *bool   // 是否打印堆栈信息
    CustomErrorBody *bool   // 是否使用自定义错误响应
    ErrorMessage    *string // 自定义错误消息
    ErrorCode       *string // 自定义错误代码
}

RequestLoggerConfig

请求日志中间件配置

type RequestLoggerConfig struct {
    Name            *string   // 中间件名称
    Order           *int      // 执行顺序
    Enable          *bool     // 是否启用请求日志
    LogBody         *bool     // 是否记录请求 Body
    MaxBodySize     *int      // 最大记录 Body 大小（字节），0 表示不限制
    SkipPaths       *[]string // 跳过日志记录的路径
    LogHeaders      *[]string // 需要记录的请求头
    SuccessLogLevel *string   // 成功请求日志级别（debug/info）
}

CorsConfig

CORS 跨域中间件配置

type CorsConfig struct {
    Name             *string        // 中间件名称
    Order            *int           // 执行顺序
    AllowOrigins     *[]string      // 允许的源
    AllowMethods     *[]string      // 允许的 HTTP 方法
    AllowHeaders     *[]string      // 允许的请求头
    ExposeHeaders    *[]string      // 暴露的响应头
    AllowCredentials *bool          // 是否允许携带凭证
    MaxAge           *time.Duration // 预检请求缓存时间
}

SecurityHeadersConfig

安全头中间件配置

type SecurityHeadersConfig struct {
    Name                    *string // 中间件名称
    Order                   *int    // 执行顺序
    FrameOptions            *string // X-Frame-Options (DENY, SAMEORIGIN, ALLOW-FROM)
    ContentTypeOptions      *string // X-Content-Type-Options (nosniff)
    XSSProtection           *string // X-XSS-Protection (1; mode=block)
    ReferrerPolicy          *string // Referrer-Policy (strict-origin-when-cross-origin, no-referrer, etc)
    ContentSecurityPolicy   *string // Content-Security-Policy
    StrictTransportSecurity *string // Strict-Transport-Security (max-age=31536000; includeSubDomains)
}

RateLimiterConfig

限流中间件配置

type RateLimiterConfig struct {
    Name      *string        // 中间件名称
    Order     *int           // 执行顺序
    Limit     *int           // 时间窗口内最大请求数
    Window    *time.Duration // 时间窗口大小
    KeyFunc   KeyFunc        // 自定义 key 生成函数（可选，默认按 IP）
    SkipFunc  SkipFunc       // 跳过限流的条件（可选）
    KeyPrefix *string        // key 前缀
}

type KeyFunc  func(c *gin.Context) string // key 生成函数类型
type SkipFunc func(c *gin.Context) bool  // 跳过条件函数类型

TelemetryConfig

遥测中间件配置

type TelemetryConfig struct {
    Name  string // 中间件名称
    Order *int   // 执行顺序（指针类型用于判断是否设置）
}

构造函数

Recovery 中间件

func NewRecoveryMiddleware(config *RecoveryConfig) common.IBaseMiddleware
func NewRecoveryMiddlewareWithDefaults() common.IBaseMiddleware

RequestLogger 中间件

func NewRequestLoggerMiddleware(config *RequestLoggerConfig) common.IBaseMiddleware
func NewRequestLoggerMiddlewareWithDefaults() common.IBaseMiddleware

CORS 中间件

func NewCorsMiddleware(config *CorsConfig) common.IBaseMiddleware
func NewCorsMiddlewareWithDefaults() common.IBaseMiddleware

SecurityHeaders 中间件

func NewSecurityHeadersMiddleware(config *SecurityHeadersConfig) common.IBaseMiddleware
func NewSecurityHeadersMiddlewareWithDefaults() common.IBaseMiddleware

RateLimiter 中间件

func NewRateLimiterMiddleware(config *RateLimiterConfig) common.IBaseMiddleware
func NewRateLimiterMiddlewareWithDefaults() common.IBaseMiddleware

Telemetry 中间件

func NewTelemetryMiddleware(config *TelemetryConfig) common.IBaseMiddleware
func NewTelemetryMiddlewareWithDefaults() common.IBaseMiddleware

常量

执行顺序常量

const (
    OrderRecovery        = 0   // panic 恢复中间件（最先执行）
    OrderRequestLogger   = 50  // 请求日志中间件
    OrderCORS            = 100 // CORS 跨域中间件
    OrderSecurityHeaders = 150 // 安全头中间件
    OrderRateLimiter     = 200 // 限流中间件（认证前执行）
    OrderTelemetry       = 250 // 遥测中间件
    OrderAuth            = 300 // 认证中间件（预留）
)

响应头常量（RateLimiter）

const (
    RateLimitLimitHeader     = "X-RateLimit-Limit"     // 时间窗口内最大请求数
    RateLimitRemainingHeader = "X-RateLimit-Remaining" // 剩余可用请求数
    RateLimitResetHeader     = "X-RateLimit-Reset"     // 窗口重置时间
)

业务层封装

在业务项目中，可以定义自己的中间件接口并封装 litemiddleware 的实现：

// internal/middlewares/cors_middleware.go
package middlewares

import (
    "github.com/lite-lake/litecore-go/common"
    "github.com/lite-lake/litecore-go/component/litemiddleware"
)

type ICorsMiddleware interface {
    common.IBaseMiddleware
}

func NewCorsMiddleware() ICorsMiddleware {
    return litemiddleware.NewCorsMiddlewareWithDefaults()
}

func NewProductionCorsMiddleware() ICorsMiddleware {
    allowOrigins := []string{"https://example.com"}
    allowCredentials := true
    return litemiddleware.NewCorsMiddleware(&litemiddleware.CorsConfig{
        AllowOrigins:     &allowOrigins,
        AllowCredentials: &allowCredentials,
    })
}

性能优化建议

• RequestLogger：生产环境关闭 Body 记录（LogBody: false）
• Recovery：生产环境关闭堆栈打印（PrintStack: false）
• RateLimiter：合理设置 Limit 和 Window，避免过度限制
• SkipFunc：使用 SkipFunc 跳过内部请求或健康检查的限流

版本历史

v2.0.0 (2026-01-24)

• 目录重构：从 component/middleware 迁移至 component/litemiddleware
• 包名变更：middleware → litemiddleware
• 配置增强：所有中间件支持通过配置自定义 Name 和 Order
• 配置重构：配置属性改为指针类型，支持可选配置
• 新增功能：RateLimiter 限流中间件
• 示例完善：添加了完整的使用示例和测试用例