API 是现代应用程序中的重要组成部分，可以用于提供数据和功能，供客户端应用程序访问。由于网络不稳定、服务器负载、网络拥堵等因素，API 请求可能会花费较长时间。这可能导致客户端应用程序在等待响应时出现延迟，最终导致用户不满意，甚至放弃使用应用程序。

为了避免这种情况，可以为 API 请求设置超时时间。超时时间是指在一定时间内，如果 API 请求没有得到响应，将自动取消该请求。这可以防止客户端应用程序一直等待 API 响应，从而提高用户体验。

1.Gin 的 Middleware

Gin 是一种轻量级的 Web 框架，用于构建高性能的 Web 应用程序。它具有快速、简单和易于使用的特点，并且具有许多可扩展的功能，如中间件。

在 Gin 框架中，中间件是一种用于拦截 HTTP 请求和响应的机制。中间件函数可以在请求到达处理函数之前或之后执行某些操作，例如：

• 登录态校验
• 权限校验
• 打印请求和响应的内容
• 设置接口超时等

Gin 框架提供了一种简单的方法来定义和使用中间件。中间件函数需要满足以下条件：

• 函数的签名必须是 func(c *gin.Context)，其中 c 是 Gin 框架中的上下文对象。
• 函数可以执行任何操作，但是必须调用 c.Next() 方法来继续执行请求处理程序和其他中间件函数。
• 如果需要在请求处理程序之后执行某些操作，可以在调用 c.Next() 之后执行。

2.gin-contrib/timeout

在 Gin 中，可以使用中间件来设置 API 请求的处理超时时间。

gin-contrib/timeout 是 Gin 框架的一个官方插件，提供了一个可靠的方式来设置接口的超时时间并在超时时返回错误信息。使用 gin-contrib/timeout 可以大大简化我们的代码，使代码更加清晰易懂。

以下是使用 gin-contrib/timeout 实现 Gin 接口超时返回的示例代码：

package mainimport ("log""net/http""time""github.com/gin-contrib/timeout""github.com/gin-gonic/gin"
)func testResponse(c *gin.Context) {c.JSON(http.StatusGatewayTimeout, gin.H{"code": http.StatusGatewayTimeout,"msg":  "timeout",})
}func timeoutMiddleware() gin.HandlerFunc {return timeout.New(timeout.WithTimeout(3000*time.Millisecond),timeout.WithHandler(func(c *gin.Context) {c.Next()}),timeout.WithResponse(testResponse),)
}func main() {r := gin.New()r.Use(timeoutMiddleware())r.GET("/slow", func(c *gin.Context) {time.Sleep(5000 * time.Millisecond)c.Status(http.StatusOK)})if err := r.Run(":8080"); err != nil {log.Fatal(err)}
}

在示例代码中，我们使用 timeout.New() 函数来创建一个中间件，并将超时时间设置为 3 秒。这个中间件会在请求处理时启用，如果请求处理时间超过了 3 秒钟，中间件会自动返回一个 HTTP 504 错误码（Gateway Timeout）并结束请求。这样我们就能够在 Gin 框架中非常方便地实现接口超时返回功能了。

访问接口 /slow 我们将会得到如下回包。

{"code": 504,"msg": "timeout"
}

3.小结

在本文中，我们介绍了为什么要给 API 设置超时时间，以及在 Gin 中使用 Middleware 设置超时时间的方法。通过合理地

关于 gin-contrib/timeout 具体实现，感兴趣的同学可以深入研究其源码。

当然，我们也可以自己实现 timeout 中间件。基于不重复造轮子的原则，建议使用官方库。

---

参考文献

OpenAI ChatGPT
Using middleware | Gin Web Framework
gin-contrib/timeout
Gin增加超时控制中间件 - 半码博客