Gin笔记一之项目建立与运行

本文首发于公众号：Hunter后端

原文链接：Gin笔记一之项目建立与运行

本篇笔记开始介绍 Golang 的 web 框架 Gin 的相关内容。

本系列笔记预计通过四到五篇笔记内容介绍 Gin 框架的核心内容，然后通过一个简单的示例介绍一个 Gin 项目的目录结构，然后介绍如何将一个 Gin 项目使用 Docker 打包部署。

此外，还将介绍在 Gin 项目里连接使用 Redis、Mongo、MySQL 等操作。

以下是本篇笔记内容：

1. 模块安装
2. 项目运行
3. 接口返回参数
4. 运行模式

1、模块安装

创建一个文件夹 gin_proj，然后进入该文件夹执行 go mod init gin_proj 初始化 Go 模块。

然后安装 gin 模块：

go get github.com/gin-gonic/gin

2、项目运行

我们在 gin_proj 文件夹下创建一个 main.go 文件，然后定义一个接口，然后返回数据的代码如下：

package mainimport ("net/http""github.com/gin-gonic/gin"
)func main() {r := gin.Default()r.GET("/test", func(c *gin.Context) {c.JSON(http.StatusOK, gin.H{"code": 0, "message": "success"})})r.Run(":9898")
}

然后在浏览器中或者使用 postman 访问 http://localhost:9898/test 就可以看到对应的结果输出。

其代码释义如下。

1. gin.Default()

gin.Default() 返回的类型是 *gin.Engine，我们可以用其定义路由和分组，设置 HTTP 请求类型，比如这里的 r.GET() 以及后面将要介绍的路由组。

2. r.GET()

r.GET() 用于设置请求的方式，比如这里是 GET 请求，如果是 post 请求可以使用 r.POST()。

GET() 方法接收两个参数，第一个参数是路由，比如这里是 /test，第二个参数是个可变参数，...HandlerFunc，可接收多个 HandlerFunc 类型，此类型是一个函数，接收 *gin.Context 参数，其定义如下：

type HandlerFunc func(*Context)

这里的第二个参数，除了路由的处理函数，我们还可以在其中加上中间件处理。

在上面的代码示例中，第二个参数用的是匿名函数，我们还可以直接将这个函数提出去：

func TestHandler(c *gin.Context) {c.JSON(http.StatusOK, gin.H{"code": 0, "message": "success"})
}func main() {r := gin.Default()r.GET("/test", TestHandler)r.Run(":9898")
}

3. r.Run()

r.Run() 接收运行时使用的端口，这里传入的是 :9898，表示运行在 9898 端口。

如果不传入参数，默认使用 8080 端口。

Run() 还返回一个 err 参数，表示运行时 error：

err := r.Run(":9898")
if err != nil {fmt.Println("gin run in 9898 error:", err)
}

3、接口返回参数

在上面 TestHandler 函数中，接收的参数是 *gin.Context，我们可以使用其处理请求流程，获取请求数据，处理响应，上下文数据传递等，这个在后面做具体的介绍。

这里返回的代码如下：

c.JSON(http.StatusOK, gin.H{"code": 0, "message": "success"})

1. c.JSON()

c.JSON() 这里返回的是 /test 接口的内容，接收两个参数，第一个是状态码，也就是 HTTP 状态码，比如 200、404 这种。

第二个参数的类型是 any，接收任意类型的数据，我们这里返回的是 gin.H{}，这个在后面再介绍。

这里的 c.JSON() 是用于向客户端返回 json 格式的数据，会将第二个参数序列化后返回。

除了 c.JSON() 外，我们还可以使用 c.String() 返回纯文本，c.HTML() 返回 HTML 页面，和其他的 c.File() 返回文件等操作。

2. http.StatusOK

http.StatusOK 是 net/http 模块下表示 HTTP 状态码的常量，其值为 200，在 c.JSON()，我们也可以直接使用 200 作为返回值。

c.JSON(200, gin.H{"code": 0, "message": "success"})

除了 http.StatusOK，还有其他 2xx，3xx，4xx，5xx 等状态码在该模块下都有定义，这里就不赘述了。

3. gin.H{}

gin.H 类型是一个 map，其定义如下：

type H map[string]any

除了像上面一个对返回的字段挨个进行赋值，我们还可以直接返回一个 struct 类型。

type TestResponse struct {Code    int    `json:"code"`Message string `json:"message"`
}func TestHandler(c *gin.Context) {response := TestResponse{Code:    0,Message: "success",}c.JSON(http.StatusOK, response)
}

4、运行模式

gin 里一共定义了三种模式，分别是 debug、release、test，其定义如下：

const (// DebugMode indicates gin mode is debug.DebugMode = "debug"// ReleaseMode indicates gin mode is release.ReleaseMode = "release"// TestMode indicates gin mode is test.TestMode = "test"
)

系统默认运行模式是 debug 模式，当我们直接运行 go run main.go 时，其输出信息如下：

[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.- using env:   export GIN_MODE=release- using code:  gin.SetMode(gin.ReleaseMode)[GIN-debug] GET    /test                     --> main.main.func1 (3 handlers)
[GIN-debug] [WARNING] You trusted all proxies, this is NOT safe. We recommend you to set a value.
Please check https://pkg.go.dev/github.com/gin-gonic/gin#readme-don-t-trust-all-proxies for details.
[GIN-debug] Listening and serving HTTP on :9898

会输出当前的运行模式，可以访问的接口等信息，这里第一行的输出还介绍了我们使用的 r := gin.Default() 会默认使用 Logger and Recovery 两个中间件，这个后面在介绍 gin.Engine 的再详细介绍。

而如果我们设置运行模式为 release 模式，控制台仅仅会在访问接口的时候输出一条访问信息，包括访问时间、耗时、请求方式和访问的接口名称：

[GIN] 2025/08/19 - 00:32:09 | 200 |     140.916µs |             ::1 | GET      "/test"

设置运行模式

我们可以通过下面的方法获取和设置运行模式：

// 获取运行模式
gin.Mode()// 设置运行模式
gin.SetMode(gin.ReleaseMode)

gin 在运行时，会先加载系统环境变量 GIN_MODE，然后根据获取的值将系统设置为对应的模式。

所以我们在部署系统时，如果是以 Docker 形式部署，可以设置此变量来设置对应的运行模式。

declare -x GIN_MODE="release"

也可以在 main.go 中直接设置：

gin.SetMode(gin.ReleaseMode)

以上就是本篇笔记全部内容，主要介绍了 gin 框架的运行方式，并介绍了一个简单示例如何设置接口并返回，还有 gin 的系统模式设置，接下来几篇笔记将详细介绍 gin.Engine 与路由的相关操作，gin.Context 与响应处理，中间件等设置。