实用指南：gin 常见中间件配置

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

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

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

安全头中间件

middlewares/security.go

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

package middlewares
import "github.com/gin-gonic/gin"
func SecurityMiddleware() gin.HandlerFunc {
  return func(c *gin.Context) {
    // 设置安全头 (在处理请求之前)
    c.Header("X-Frame-Options", "DENY") //	•	防止网页被嵌入到  中，防止点击劫持（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 才设置 HSTS
    if 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 middlewares
import (
  "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 middlewares
import (
  "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 ID
    requestID := c.GetHeader(RequestIDKey)
    // 如果没有，则生成新的 UUID
    if requestID == "" {
      requestID = uuid.New().String()
    }
    // 将 Request ID 存储到 Context 中
    c.Set(RequestIDKey, requestID)
    // 创建带 Request ID 的 context
    ctx := context.WithValue(context.Background(), utils.RequestIDKey, requestID)
    // 设置到全局 context (当前 goroutine)
    utils.SetRequestContext(ctx)
    // 设置响应头
    c.Header(RequestIDKey, requestID)
    // 继续处理请求
    c.Next()
    // 请求结束后清理 context
    utils.ClearRequestContext()
  }
}

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

请求响应日志中间件

middlewares/logging.go

package middlewares
import (
  "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 []byte
    if 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 ID
    utils.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 ID
    utils.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.ResponseWriter
  body *bytes.Buffer
}
func (w bodyLogWriter) Write(b []byte) (int, error) {
  w.body.Write(b)
  return w.ResponseWriter.Write(b)
}

注册中间件

routers/main.go

package router
import (
  "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
}