中间件

前言

在Web应用中，中间件是一个非常常见的组件，用来在请求和响应之间嵌入一些操作，比如日志记录、身份验证、错误处理等。

如果使用gin.Default()方式创建gin实例，将会包含两个中间件，一个日志记录中间件，一个异常恢复中间件。如果用gin.New()的方式示例化，将不包含中间件。

根据作用范围，可以分为三种中间件：

• 全局级，对于所有api都生效
• 路由组级，对于路由组内的所有api生效
• 路由级，只对单个api生效

下面的代码示例来自官网文档

func main() {
	// Creates a router without any middleware by default
	r := gin.New()

	// Global middleware
	// Logger middleware will write the logs to gin.DefaultWriter even if you set with GIN_MODE=release.
	// By default gin.DefaultWriter = os.Stdout
	r.Use(gin.Logger())

	// Recovery middleware recovers from any panics and writes a 500 if there was one.
	r.Use(gin.Recovery())

	// Per route middleware, you can add as many as you desire.
	r.GET("/benchmark", MyBenchLogger(), benchEndpoint)

	// Authorization group
	// authorized := r.Group("/", AuthRequired())
	// exactly the same as:
	authorized := r.Group("/")
	// per group middleware! in this case we use the custom created
	// AuthRequired() middleware just in the "authorized" group.
	authorized.Use(AuthRequired())
	{
		authorized.POST("/login", loginEndpoint)
		authorized.POST("/submit", submitEndpoint)
		authorized.POST("/read", readEndpoint)

		// nested group
		testing := authorized.Group("testing")
		testing.GET("/analytics", analyticsEndpoint)
	}

	// Listen and serve on 0.0.0.0:8080
	r.Run(":8080")
}

一个简单的自定义中间件示例

下面是一个简单的自定义中间件示例，在控制台输出请求时间、请求耗时、请求客户端、请求方法、响应码。编辑pkg/middlewares/mids.go

type mids struct{}

func NewMids() *mids {
	return &mids{}
}

func (m *mids) Simple(c *gin.Context) {
	start := time.Now()
	c.Next()  // 
	current := time.Now()
	status := c.Writer.Status()
	method := c.Request.Method
	path := c.FullPath()
	clientIP := c.ClientIP()

	fmt.Printf("%s | %s %s %s cost %v, status: %d\n", current.Format("2006-01-02 15:04:05"), clientIP, method, path, current.Sub(start), status)
}

编辑main.go

func main() {
	mids := middlewares.NewMids()
	router := gin.New()
	router.Use(gin.Recovery())
	router.Use(mids.Simple)

	router.GET("/header", func(c *gin.Context) {
		userAgent := c.GetHeader("User-Agent")
		log.Info("User-Agent", "userAgent", userAgent)
		c.String(http.StatusOK, userAgent)
	})

	router.Run("127.0.0.1:8000")
}

运行输出结果

2024-11-23 22:18:49 | 127.0.0.1 GET /header cost 512.7µs, status: 200

中间件中不要在goroutine直接使用context

如果在中间件或视图函数中启动一个新的goroutine，不要直接使用原始context, 应该复制一份context。参见官方文档 Goroutines inside a middleware

func main() {
	r := gin.Default()

	r.GET("/long_async", func(c *gin.Context) {
		// create copy to be used inside the goroutine
		cCp := c.Copy()
		go func() {
			// simulate a long task with time.Sleep(). 5 seconds
			time.Sleep(5 * time.Second)

			// note that you are using the copied context "cCp", IMPORTANT
			log.Println("Done! in path " + cCp.Request.URL.Path)
		}()
	})

	r.GET("/long_sync", func(c *gin.Context) {
		// simulate a long task with time.Sleep(). 5 seconds
		time.Sleep(5 * time.Second)

		// since we are NOT using a goroutine, we do not have to copy the context
		log.Println("Done! in path " + c.Request.URL.Path)
	})

	// Listen and serve on 0.0.0.0:8080
	r.Run(":8080")
}

日志记录

日志记录的中间件用于记录请求和响应的详细日志，帮助调试和监控，比如记录HTTP请求的客户端IP、http方法、api路径、状态码、请求耗时等等。

gin自带一个gin.Logger中间件来记录路由日志，也可以参考上面示例，结合单独的日志模块，将路由日志向不同位置输出。

恢复

用于捕获应用中的panic错误，避免应用崩溃，保证web服务的稳定性。

gin自带一个gin.Recovery()中间件来做异常恢复。

跨域资源共享（CORS）

允许或限制不同域名的客户端访问资源，特别是在开发前后端分离的应用时

认证鉴权

下一节单独讲解

限流

用于控制客户端请求的速率，防止滥用 API。常见方法有漏桶和令牌桶

响应格式化

统一所有响应的格式，如将响应包装成一个标准的结构体。

func JSONResponseMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Next()
        status := c.Writer.Status()
        if status >= 400 {
            c.JSON(status, gin.H{"status": "error"})
        } else {
            c.JSON(status, gin.H{"status": "success"})
        }
    }
}

r := gin.Default()
r.Use(JSONResponseMiddleware())

请求跟踪

在每个请求中生成唯一的标识符（如请求 ID），以便追踪日志和调试。

func RequestIDMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        requestID := uuid.New().String()
        c.Set("request_id", requestID)
        c.Writer.Header().Set("X-Request-ID", requestID)
        c.Next()
    }
}

r := gin.Default()
r.Use(RequestIDMiddleware())