20 go语言（golang） - gin框架安装及使用（一）

一、简介

Gin是一个用Go语言编写的高性能Web框架，专注于构建快速、可靠的HTTP服务。它以其速度和简洁性而闻名，非常适合用于开发RESTful API。

高性能：Gin使用了httprouter进行路由管理，这是一个轻量级且非常快速的HTTP请求路由器。
中间件支持：Gin提供了一种简单的方法来创建和使用中间件，可以在请求处理过程中执行额外的操作，如日志记录、身份验证等。
错误管理：内置了错误处理机制，可以在请求生命周期内捕获并处理错误，确保应用程序稳定运行。
JSON渲染：提供了便捷的方法来生成JSON响应，这对于构建API非常有用。
路由组：支持将路由组织成组，以便更好地管理复杂应用程序中的不同模块或版本控制。
优雅的API设计：提供了一套简洁易用的API，使得开发者可以快速上手并实现复杂功能。

二、安装

使用 go get 命令来下载并安装Gin包，详细参考官网文档：官方指引

bash 复制代码

go get -u github.com/gin-gonic/gin

三、使用

3.1 代码

下面是一个简单的示例程序，展示如何使用Gin创建一个Web服务器：

go 复制代码

package main

import (
	"github.com/gin-gonic/gin"
	"net/http"
	"testing"
)

func Test1(t *testing.T) {
	// 创建一个带有Logger和Recovery中间件（用于日志记录和恢复崩溃）的默认Gin引擎。
	r := gin.Default()

	// 定义一个GET请求路由，当访问"/ping"时会调用指定匿名函数返回JSON响应。
	r.GET("/ping", func(c *gin.Context) {
		// 返回JSON格式的数据响应，其中`http.StatusOK`表示200状态码，而`gin.H{}`用于构造JSON对象。
		c.JSON(http.StatusOK, gin.H{
			"message": "pong",
		})
	})

	// 启动HTTP服务器，监听8080端口（如未指定端口，将默认为:8080）。
	r.Run(":8080")
}

3.2 运行程序

在goland中右键运行
打开浏览器或使用工具（如curl或Postman）访问 http://localhost:8080/ping后，JSON响应：
json 复制代码
```
{"message":"pong"}
```

四、组成

Gin 是一个用 Go 语言编写的高性能 HTTP Web 框架，特别适合用于构建微服务和快速开发 RESTful API。Gin 的组成主要包括以下几个核心部分：

Router（路由器）
- Gin 使用基于树结构的路由机制来处理 HTTP 请求。它支持动态路由参数、分组路由以及中间件。
- 路由器负责将请求路径映射到相应的处理函数。
Context（上下文）
- gin.Context 是 Gin 中最重要的结构之一，它在请求生命周期内传递信息。
- Context 提供了对请求和响应对象的访问，以及用于存储数据、设置状态码、返回 JSON 等方法。
Middleware（中间件）
- 中间件是可以在请求被最终处理之前或之后执行的一段代码，用于实现日志记录、错误恢复、认证等功能。
- Gin 支持全局中间件和特定路由组或单个路由使用的中间件。
Handlers（处理函数）
- 处理函数是实际执行业务逻辑的位置，每个路由都会关联一个或多个处理函数。
- 这些函数接收 gin.Context 参数，通过它们可以获取请求数据并生成响应。
Error Handling（错误处理）
- Gin 提供了一种机制来捕获和管理应用程序中的错误，可以通过 Context 的方法进行错误报告和恢复操作。
Rendering and Responses（渲染与响应）
- 支持多种格式的数据输出，包括 JSON、XML 和 HTML 渲染等，方便客户端消费不同类型的数据格式。
Binding and Validation（绑定与验证）
- 自动将 HTTP 请求中的数据绑定到结构体，并支持对输入数据进行验证，以确保其符合预期格式和规则。
Templates (模板)
- 虽然不是框架核心，但 Gin 支持集成 HTML 模板引擎，用于生成动态网页内容。

4.1 Router（路由器）

Gin 的路由器是其核心组件之一，负责将 HTTP 请求路径映射到相应的处理函数。它采用高效的树结构来管理路由，从而提高请求匹配速度。

4.1.1 基本路由

Gin 提供了简单的方法来定义基本的 HTTP 路由。例如，可以使用 GET, POST, PUT, DELETE 等方法来注册不同类型的请求。

go 复制代码

func postTest(context *gin.Context) {
	context.JSON(http.StatusOK, gin.H{
		"message": "post_test_success",
	})
}

func Test2(t *testing.T) {
	r := gin.Default()

	r.POST("/post_test", postTest)

	r.Run()
}

4.1.2 动态路由参数

支持在 URL 中定义动态参数，允许从 URL 中提取变量。

go 复制代码

func Test3(t *testing.T) {
	r := gin.Default()

	r.GET("/get_test/:name", func(c *gin.Context) {
		name := c.Param("name")
		c.JSON(http.StatusOK, gin.H{
			"message": "hello:" + name,
		})
	})

	r.Run()

}

4.1.3 查询字符串和表单参数

可以通过上下文对象轻松获取查询字符串和表单数据。

go 复制代码

func Test4(t *testing.T) {
	r := gin.Default()

	r.POST("/form_post", func(c *gin.Context) {
		name := c.PostForm("name")
		nickname := c.DefaultPostForm("nickname", "昵称")
		c.JSON(200, gin.H{
			"name":     name,
			"nickname": nickname,
		})
	})
	r.Run()
}

4.1.4 分组路由（Route Groups）

允许对一组具有共同前缀或中间件的路由进行分组管理。这有助于组织代码并应用共享行为。

go 复制代码

func Test5(t *testing.T) {
	r := gin.Default()
	group := r.Group("/v1")
	handler := func(c *gin.Context) {
		println("调用了地址：" + c.Request.Host + c.Request.URL.Path)
	}
	{
		group.GET("/login", handler)
		group.GET("/submit", handler)
		group.GET("/listData", handler)
	}
	r.Run()
}

输出

调用了地址：localhost:8080/v1/login
[GIN] 2024/12/05 - 18:59:09 | 200 |      26.787µs |             ::1 | GET      "/v1/login"
调用了地址：localhost:8080/v1/submit
[GIN] 2024/12/05 - 18:59:24 | 200 |      11.511µs |             ::1 | GET      "/v1/submit"
调用了地址：localhost:8080/v1/listData
[GIN] 2024/12/05 - 18:59:31 | 200 |      10.746µs |             ::1 | GET      "/v1/listData"

4.1.5 优先级与冲突解决

Gin 的树形结构使得精确匹配路径比通配符路径优先级更高，因此 /v1/login 会比 /v1/:name 优先匹配。

go 复制代码

func Test6(t *testing.T) {
	r := gin.Default()
	group := r.Group("/v1")
	handler := func(c *gin.Context) {
		println("调用了地址：" + c.Request.Host + c.Request.URL.Path)
	}
	handler2 := func(c *gin.Context) {
		name := c.Param("name")
		println("调用了地址：" + c.Request.Host + c.Request.URL.Path)
		c.JSON(http.StatusOK, gin.H{
			"message": "hello:" + name,
		})
	}
	{
		group.GET("/login", handler)
		group.GET("/:name", handler2)
	}
	r.Run()
}

4.2 Context（上下文）

gin.Context 是一个非常重要的结构体，它在每个请求的生命周期内被创建，并贯穿整个处理过程。上下文提供了丰富的方法和属性，用于简化请求数据的获取、响应生成以及中间件之间的数据共享。

4.2.1 请求数据访问

Context 提供了多种方法来访问 HTTP 请求的数据，包括路径参数、查询参数、表单数据和 JSON 数据等。

go 复制代码

type MyStruct struct {
	Name string `json:"name"`
	Age  int    `json:"age"`
}

func Test7(t *testing.T) {
	r := gin.Default()
	r.GET("/:name", func(c *gin.Context) {

		// 获取路径参数
		name := c.Param("name")

		// 获取查询参数
		page := c.DefaultQuery("page", "0") // 带默认值

		// 获取表单参数
		message := c.PostForm("message")

		// 将请求body中的 JSON 数据 解析到结构体中
		var jsonData MyStruct
		if err := c.ShouldBindJSON(&jsonData); err != nil {
			c.JSON(400, gin.H{"error": err.Error()}) // 如果解析错误，则返回400报错
			return
		}

		println("调用了地址：" + c.Request.Host + c.Request.URL.Path)
		c.JSON(http.StatusOK, gin.H{
			"name":     name,
			"page":     page,
			"message":  message,
			"jsonData": jsonData,
		})
	})
	r.Run()
}

4.2.2 响应生成

上下文对象提供了一系列方法来构建 HTTP 响应，包括设置状态码、返回 JSON/XML/HTML 等。

go 复制代码

func Test8(t *testing.T) {
	r := gin.Default()
	group := r.Group("/test_response")

	{
		group.GET("string", func(c *gin.Context) {
			// 返回字符串
			c.String(200, "string...")
		})

		group.GET("json", func(c *gin.Context) {
			// 返回json格式
			c.JSON(200, gin.H{
				"json": "json...",
			})
		})

    // 返回html页面，需要先加载模板
		r.LoadHTMLGlob("./html/*")
		group.GET("html", func(c *gin.Context) {
			c.HTML(200, "index.html", gin.H{
				"title": "这是个标题。。。",
			})
		})
	}

	r.Run()
}

项目目录下建html文件夹，里面新建文件index.html，内容为

html 复制代码

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{{ .title }}</title>
</head>
<body>
    <h1>Welcome to {{ .title }}</h1>
</body>
</html>

4.2.3 状态码与头信息

可以通过上下文设置 HTTP 状态码和头信息。

go 复制代码

  c.Status(200)

  c.Header("Content-Type", "application/json")  // 在使用 Gin 返回 JSON 响应时，c.JSON() 方法会自动将响应的内容类型设置为 application/json，所以通常不用手动设置

4.2.4 流控制与错误处理

支持流控制，比如终止请求链或跳过剩余中间件，还可以进行错误管理。

go 复制代码

func Test9(t *testing.T) {

	r := gin.Default()
	r.GET("/test_error/:bool", func(c *gin.Context) {
		param := c.Param("bool")
		// 如果用户调用的是/test_error/true，则直接返回{ "error": "测试错误" }
		if param == "true" {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "测试错误"})
			return
		}

		// 否则才正常返回
		c.JSON(200, gin.H{
			"success": "正常返回",
		})
	})

	r.Run()
}

4.2.5 键值存储（Set/Get）

上下文允许在不同处理中传递数据，可以使用键值对存储临时数据。

go 复制代码

c.Set("mykey","value")

value,_:=c.Get ("mykey")

4.2.6 并发安全性

Gin 的 Context 是不支持跨 goroutine 使用的，因为它不是线程安全的。如果需要跨 goroutine 使用 Context 中的信息，应该提前将所需的数据提取出来。
每个 HTTP 请求都会创建一个新的 Context 实例，该实例仅在处理该请求的过程中有效。一旦请求处理完毕，Gin 会回收这个 Context 对象以供将来的请求使用。因此，在另一个 goroutine 中持有对同一 Context 的引用可能导致不可预测的问题，因为原始请求可能已经结束。

4.3 Middleware（中间件）

中间件在处理请求的过程中起到拦截和处理的作用，可以在请求到达最终路由之前进行一些操作，比如日志记录、身份验证、跨域资源共享（CORS）、错误恢复等。

注！中间件的概念与Java中的切面（Aspect-Oriented Programming，AOP）在某些方面是像的！

定义：中间件是一个函数，它接收gin.Context作为参数，并通过调用Next()来执行下一个中间件或最终处理器。
链式调用：Gin中的中间件采用链式调用方式，多个中间件可以按顺序依次执行。
全局与局部：可以将中间件应用于整个应用程序，也可以仅限于特定路由。

4.3.1 默认中间件

Default引擎已经包含了两个默认中间件Logger()和Recovery()，r := gin.Default()源码：

go 复制代码

    // Default returns an Engine instance with the Logger and Recovery middleware already attached.
    func Default(opts ...OptionFunc) *Engine {
       debugPrintWARNINGDefault()
       engine := New()
       engine.Use(Logger(), Recovery()) // 配置了两个中间件
       return engine.With(opts...)
    }

gin.Logger()
- 功能：这个中间件用于记录HTTP请求日志，包括请求的路径、方法、状态码、处理时间等信息。
- 使用：通常用于开发和生产环境下的请求日志记录，帮助开发者了解应用程序的运行情况。
gin.Recovery()
- 功能：这个中间件用于从panic（程序崩溃）中恢复，并返回500错误响应。它确保即使发生了未捕获的异常，服务器也不会崩溃。
- 使用：建议在生产环境下始终启用，以提高应用程序的稳定性和可靠性。

4.3.1 全局中间件

全局中间件会对所有请求生效，通常用于通用功能，如日志记录或错误恢复。

通过r.Use()方法使用中间件：

go 复制代码

// 使用Logger和Recovery两个默认提供的全局中间件
r.Use(gin.Logger())
r.Use(gin.Recovery())

4.3.2 路由组级别的中间件

可以将某些特定功能限制在某个路由组内，而不是整个应用程序。

go 复制代码

func Test10(t *testing.T) {
	r := gin.Default()

	group := r.Group("/v1")

	// 对分组使用一个中间件
	group.Use(func(context *gin.Context) {
		fmt.Println("进入分组中间件")
	})
	
	group.GET("/group", func(c *gin.Context) {
		fmt.Println("group 返回json。。。")
		c.JSON(200, gin.H{
			"msg": "success！",
		})
	})

	r.GET("/v2", func(c *gin.Context) {
		fmt.Println("v2 返回json")
		c.JSON(200, gin.H{
			"msg": "success！",
		})
	})

	r.Run()

}

输出

进入分组中间件
group 返回json。。。
[GIN] 2024/12/12 - 14:57:16 | 200 |      28.996µs |             ::1 | GET      "/v1/group"
v2 返回json
[GIN] 2024/12/12 - 14:57:18 | 200 |      23.899µs |             ::1 | GET      "/v2"

4.3.3 实现自定义Middleware

自定义Middleware需要实现具体逻辑并返回gin.HandlerFunc类型。以下是一个简单示例：

go 复制代码

func MyMiddleware() gin.HandlerFunc {
	return func(c *gin.Context) {
		fmt.Println("这是定义函数返回中间件的方式使用中间件")
	}
}

func Test11(t *testing.T) {

	r := gin.New()
	r.Use(MyMiddleware())

	r.Use(func(c *gin.Context) {
		fmt.Println("这是匿名函数的方式使用中间件")
	})

	r.GET("/test", func(c *gin.Context) {
		fmt.Println("正常返回")
	})

	r.Run()
}

输出

这是定义函数返回中间件的方式使用中间件
这是匿名函数的方式使用中间件
正常返回

为什么 Golang 知道这是一个 HandlerFunc？

Golang 是一种静态类型语言，它通过类型推断和接口匹配机制来判断某个对象是否实现了某个接口或符合某种类型。在 Gin 中，只要你的自定义方法符合上述签名，就会被自动识别为 HandlerFunc 类型。