gin 常见中间件配置

这里主要配置 请求日志中间件、跨域中间件、trace_id 中间件、安全头中间件

一般来说，这个中间件的信息 就是放在 middlewares/* 里面的*.go 进行操作

➜  middlewares git:(main) tree 
.
├── cors.go
├── logging.go
├── request_id.go
└── security.go1 directory, 4 files
➜  middlewares git:(main) 

安全头中间件

middlewares/security.go

增强 Web 安全性的中间件，用于 Gin 框架中的请求处理流程中。

package middlewaresimport "github.com/gin-gonic/gin"func SecurityMiddleware() gin.HandlerFunc {return func(c *gin.Context) {// 设置安全头 (在处理请求之前)c.Header("X-Frame-Options", "DENY") //	•	防止网页被嵌入到 <iframe> 中，防止点击劫持（Clickjacking）c.Header("Content-Security-Policy", "frame-ancestors 'none'") //更强的防 iframe 策略，不允许任何来源嵌入本页面c.Header("Referrer-Policy", "no-referrer")//不发送 Referer 请求头，防止隐私泄露c.Header("Cross-Origin-Opener-Policy", "same-origin")c.Header("X-Content-Type-Options", "nosniff")c.Header("X-XSS-Protection", "1; mode=block") //禁止浏览器 MIME 类型嗅探，防止脚本注入// HTTPS 才设置 HSTSif c.Request.TLS != nil || c.GetHeader("X-Forwarded-Proto") == "https" {c.Header("Strict-Transport-Security", "max-age=63072000; includeSubDomains; preload")}// 处理请求c.Next() //执行下一个中间件或 handler：}
}>>>>>>返回一个符合 Gin 规范的中间件函数 gin.HandlerFunc，用于设置多个安全相关的响应头。
>>>>>>func(c *gin.Context) 类型的函数（即 gin.HandlerFunc）

功能	实现方式
防 iframe 嵌套劫持	X-Frame-Options, Content-Security-Policy
禁止 Referer 泄露	Referrer-Policy
强制同源隔离	Cross-Origin-Opener-Policy
防止 MIME 嗅探	X-Content-Type-Options
启用浏览器 XSS 过滤器	X-XSS-Protection
启用 HTTPS 严格传输策略	Strict-Transport-Security（仅在 HTTPS 下设置）

func 函数名(参数列表) 返回类型 {// 函数体return 返回值
}
func add(a int, b int) int {return a + b
}
函数也是一种值，就像字符串、整数一样，是可以 return 的！
func gen() func() string {return func() string {return "hello"}
}

跨域中间件

middlewares/cors.go

动态设置允许哪些前端域名跨域访问后端接口，防止跨域请求被浏览器拦截。

package middlewaresimport ("gin-api-template/utils""time""github.com/gin-contrib/cors""github.com/gin-gonic/gin"
)func CORSMiddleware() gin.HandlerFunc {allowedOrigins := []string{} //动态设置允许跨域的域名列表if utils.AppConfig != nil && len(utils.AppConfig.CORSAllowedOrigins) > 0 {allowedOrigins = utils.AppConfig.CORSAllowedOrigins} else if utils.IsDevelopment() {allowedOrigins = []string{"http://localhost:3000","http://localhost:8000","http://127.0.0.1:3000",}}config := cors.Config{AllowOrigins:     allowedOrigins,AllowMethods:     []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},AllowHeaders:     []string{"Origin", "Content-Type", "Authorization", "X-Request-ID"},ExposeHeaders:    []string{"X-Request-ID"},AllowCredentials: true,MaxAge:           12 * time.Hour,}return cors.New(config)
}

字段	含义
AllowOrigins	允许哪些域名跨域访问
AllowMethods	允许的请求方法（默认 OPTIONS 也必须允许）
AllowHeaders	前端允许携带哪些 Header 发起请求
ExposeHeaders	浏览器允许访问响应头中的哪些字段（如 X-Request-ID）
AllowCredentials	是否允许携带 Cookie
MaxAge	预检请求的缓存时长（12 小时内不会再次发 OPTIONS）

trace_id 中间件

middlewares/request_id.go

✅ 为每一个请求自动分配或传递一个唯一的 Request ID，用于日志追踪、请求链路追踪、错误排查等。

package middlewaresimport ("context""gin-api-template/utils""github.com/gin-gonic/gin""github.com/google/uuid"
)const RequestIDKey = "X-Request-ID"// RequestIDMiddleware 请求ID中间件
func RequestIDMiddleware() gin.HandlerFunc {return func(c *gin.Context) {// 先检查请求头中是否已有 Request IDrequestID := c.GetHeader(RequestIDKey)// 如果没有，则生成新的 UUIDif requestID == "" {requestID = uuid.New().String()}// 将 Request ID 存储到 Context 中c.Set(RequestIDKey, requestID)// 创建带 Request ID 的 contextctx := context.WithValue(context.Background(), utils.RequestIDKey, requestID)// 设置到全局 context (当前 goroutine)utils.SetRequestContext(ctx)// 设置响应头c.Header(RequestIDKey, requestID)// 继续处理请求c.Next()// 请求结束后清理 contextutils.ClearRequestContext()}
}

• 日志加上 RequestID，便于搜索同一个请求的全链路日志
• 链路追踪（如 Zipkin、Jaeger）
• 接口调试时，前端可将 X-Request-ID 提交给后端排查问题

请求响应日志中间件

middlewares/logging.go

package middlewaresimport ("bytes""fmt""io""time""gin-api-template/utils""github.com/gin-gonic/gin"
)// LoggingMiddleware API请求响应日志中间件
func LoggingMiddleware() gin.HandlerFunc {return func(c *gin.Context) {startTime := time.Now()// 读取请求体var requestBody []byteif c.Request.Body != nil {requestBody, _ = io.ReadAll(c.Request.Body)// 重新设置请求体，因为读取后会被消耗c.Request.Body = io.NopCloser(bytes.NewBuffer(requestBody))}// 创建自定义的响应写入器来捕获响应blw := &bodyLogWriter{body: bytes.NewBufferString(""), ResponseWriter: c.Writer}c.Writer = blw// 记录请求信息 - 自动包含 Request IDutils.LogInfo(fmt.Sprintf("Request: %s %s | IP: %s | User-Agent: %s | Body: %s",c.Request.Method,c.Request.URL.Path,c.ClientIP(),c.Request.UserAgent(),string(requestBody)))// 处理请求c.Next()// 计算处理时间duration := time.Since(startTime)// 记录响应信息 - 自动包含 Request IDutils.LogInfo(fmt.Sprintf("Response: %s %s | Status: %d | Duration: %v | Response: %s",c.Request.Method,c.Request.URL.Path,c.Writer.Status(),duration,blw.body.String()))}
}// bodyLogWriter 自定义响应写入器
type bodyLogWriter struct {gin.ResponseWriterbody *bytes.Buffer
}func (w bodyLogWriter) Write(b []byte) (int, error) {w.body.Write(b)return w.ResponseWriter.Write(b)
}

注册中间件

routers/main.go

package routerimport ("gin-api-template/middlewares""github.com/gin-gonic/gin"
)func SetupRouter() *gin.Engine {// 使用 gin.New() 而不是 gin.Default()，避免默认的日志中间件r := gin.New()// 添加 Recovery 中间件（防止 panic 导致服务崩溃）r.Use(gin.Recovery())// 使用安全头中间件 (应该在最前面)r.Use(middlewares.SecurityMiddleware())// 使用 CORS 中间件r.Use(middlewares.CORSMiddleware())// 使用 Request ID 中间件r.Use(middlewares.RequestIDMiddleware())// 使用我们自定义的日志中间件r.Use(middlewares.LoggingMiddleware())// 注册各个模块的路由setupHealthRoutes(r)// setupUserRoutes(r)// setupAuthRoutes(r)// setupProductRoutes(r)// 在这里添加更多路由模块...return r
}