一文入门Gin框架

Gin框架学习

Gin是一个用Go语言实现的高性能HTTP Web框架，是Go语言生态中最受欢迎的Web框架之一，以其高性能、轻量级和简洁的API设计著称。本篇文章着重介绍Gin框架的基础内容。尽管操作该框架只需要掌握相关api，但是作为初学者对api的参数或者别的方面仍会有很大疑惑，本篇文章将尽量详细基础地解释Gin框架

在正式开始Gin框架的学习前，需要先了解一些专业术语，否则api的学习调用会稀里糊涂的。

一.路由和路由引擎

• 路由：我们常用的网址是一个URL，URL 路径是 URL中资源的“地址”（比如 /users、/posts/123）。路由则是 “导航规则”—— 它规定了 “当用户访问这个路径时，应该由哪个函数 / 方法来处理请求”

router.GET("/users", getUsers)  // 当访问 /users 时，执行 getUsers 函数
router.POST("/users", createUser)  // 当访问 /users 且用 POST 方法时，执行 createUser 函数
router.GET("/posts/:id", getPost)  // 当访问 /posts/123 时，执行 getPost 函数（并提取 id=123）

​ 这里的 /users、/posts/:id 是 URL 路径，而 “路径 + 请求方法（GET/POST 等）+ 处理函数” 的绑定关系，才是完整的路由。这里补充一个小知识，浏览器能直接输入并搜索的都是get请求，post请求无法直接在浏览器上输入搜索，可以用本地地址试一下。

• 路由引擎是路由的 “管理者”：负责管理所有注册的路由规则，接收客户端请求后，根据请求的 URL 和方法找到匹配的路由，并执行对应的处理函数。简单来说，路由引擎的就是根据接收到的HTTP请求信息（如URL路径和方法）快速匹配并执行对应的处理函数

总结一下，路由是 “数据”，路由引擎是 “处理逻辑”，开发者定义的每一条路由（如 r.GET("/users", getUsers)）都是一条数据记录，包含 “路径 + 方法 + 处理函数” 三要素。路由引擎则是一套逻辑，负责存储这些路由数据、解析请求、匹配路由、执行处理函数。

二.Gin框架基础用法

直接上代码，下面这是一个简单的gin框架

package mainimport ("github.com/gin-gonic/gin""net/http"
)func main() {// 创建默认引擎(包含Logger和Recovery中间件)r := gin.Default()// 定义路由r.GET("/ping", func(c *gin.Context) {c.JSON(http.StatusOK, gin.H{"message": "pong",})})// 启动服务(默认8080端口)r.Run()
}

• 上面提到路由引擎是路由的的管理者，后端写接口首先需要一个路由引擎。路由引擎通过 gin.Default() 或 gin.New() 创建，提供 GET、POST 等方法注册路由规则。

  • gin.Default()默认包含日志（Logger）和错误恢复（Recovery）中间件，关于中间件下面会讲到
  • gin.New() 创建纯净实例，需手动添加中间件

• 创建了路由引擎后就可以注册对应的路由。：r.GET("/hello", ...) 是向路由引擎 r 注册一条路由规则（路径为 /hello，方法为 GET，处理函数为后面的匿名函数）。当客户端发起 GET /ping 请求时，路由引擎 r 会根据之前注册的规则，自动匹配到这条路由，并调用对应的处理函数来生成响应。

  注册的路由处理函数（匿名函数）定义如何处理请求并生成响应的逻辑。

  匿名函数 func(c *gin.Context) { ... } 是 Gin 的请求处理函数（Handler），c *gin.Context是Gin封装的一个请求上下文对象，它包含了当前HTTP请求的所有信息，封装的有HTTP方法、URL、请求头、请求体、路径参数等。其核心职责是：

  • 接收请求：通过 c *gin.Context 参数访问请求数据（如路径参数、查询参数、请求体等）。
  • 执行业务逻辑：如数据库操作、数据验证等（示例中未体现，实际开发需补充）。
  • 生成响应：通过 c.JSON() 等方法向客户端返回数据或状态码。

Gin 提供多种方法返回数据，常见的有：

方法	作用	示例
c.JSON()	返回 JSON 格式数据	c.JSON(200, gin.H{"key":"value"})
c.String()	返回纯文本	c.String(200, "text")
c.HTML()	渲染 HTML 模板	c.HTML(200, "index.html", data)
c.File()	返回文件（如下载）	c.File("path/to/file.pdf")

举个例子， c.JSON(200, gin.H{"message": "DELETE"}) 表示：

• 状态码 200：HTTP 成功状态。
• 响应体：JSON 格式数据 {"message": "DELETE"}。

三.路由分组

我们可以将拥有共同URL前缀(域名)的路由划分为一个路由组，这样看着可以更清晰

r := gin.Default()userGroup := r.Group("/user"){userGroup.GET("/index", func(c *gin.Context) {...})userGroup.GET("/login", func(c *gin.Context) {...})userGroup.POST("/login", func(c *gin.Context) {...})}

这样分组后api接口就变成了“ip:端口/user/index”(客户端调用**/index**接口)

四.Gin中间件

对于上面的简单代码，用户调用相关路由时后端会直接用路由函数，但是上面的路由函数都是匿名无法重复使用，当我们有很多公共业务逻辑比如登录注册等就需要写很多遍相同的代码，中间件就可以解决这一问题。Gin框架允许开发者在处理请求的过程中，加入用户自己的钩子（Hook）函数。这个钩子函数就叫中间件，中间件适合处理一些公共的业务逻辑，比如登录认证、权限校验、数据分页、记录日志、耗时统计等。

Gin中的中间件必须是一个gin.HandlerFunc类型。

中间件的注册方法有多种，r.Use() 一般用于Gin框架中全局注册中间件。

这样全局注册后，会绑定r的所有路由，客户端访问对应api时，后端会执行该中间件和对应的路由函数，执行顺序是

中间件开始 → 路由匿名函数执行 → 中间件结束，比如下面，当客户端访问hello接口时，调用顺序看下面的注释。

func LoggerMiddleware(c *gin.Context) {fmt.Println("中间件开始") // 1. 先执行c.Next()               // 2. 移交控制权fmt.Println("中间件结束") // 5. 最后执行（响应阶段）
}func main() {r := gin.Default()r.Use(LoggerMiddleware) // 注册全局中间件r.GET("/hello", func(c *gin.Context) {fmt.Println("路由匿名函数执行") // 3. 执行业务逻辑c.String(200, "Hello")   // 4. 生成响应})r.Run(":8080")
}

也可以为某个路由单独注册中间件，将中间件函数作为参数插入到路径和路由函数中即可，写法如下

	r.GET("/test2", StatCost(), func(c *gin.Context) {name := c.MustGet("name").(string) // 从上下文取值log.Println(name)c.JSON(http.StatusOK, gin.H{"message": "Hello world!",})})

还可以为路由组注册中间件

shopGroup := r.Group("/shop", StatCost())

这样就给一个shopGroup的路由组注册了StatCost的中间件

五.总结

本文是一篇完全基础的gin教程，gin中还有很多功能如响应渲染，异常处理等方面需要学习