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

本文首发于公众号：Hunter后端
原文链接：Gin笔记一之项目建立与运行

本篇笔记开始介绍 Golang 的 web 框架 Gin 的相关内容。
本系列笔记预计通过四到五篇笔记内容介绍 Gin 框架的核心内容，然后通过一个简单的示例介绍一个 Gin 项目的目录结构，然后介绍如何将一个 Gin 项目使用 Docker 打包部署。
此外，还将介绍在 Gin 项目里连接使用 Redis、Mongo、MySQL 等操作。
以下是本篇笔记内容：

• 模块安装
  
• 项目运行
  
• 接口返回参数
  
• 运行模式
  

1、模块安装

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

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

复制代码

2、项目运行

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

1. package main
3. import (
4.     "net/http"
6.     "github.com/gin-gonic/gin"
7. )
9. func main() {
10.     r := gin.Default()
11.     r.GET("/test", func(c *gin.Context) {
12.         c.JSON(http.StatusOK, gin.H{"code": 0, "message": "success"})
13.     })
14.     r.Run(":9898")
15. }

复制代码

然后在浏览器中或者使用 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 参数，其定义如下：

1. type HandlerFunc func(*Context)

复制代码

这里的第二个参数，除了路由的处理函数，我们还可以在其中加上中间件处理。
在上面的代码示例中，第二个参数用的是匿名函数，我们还可以直接将这个函数提出去：

1. func TestHandler(c *gin.Context) {
2.     c.JSON(http.StatusOK, gin.H{"code": 0, "message": "success"})
3. }
5. func main() {
6.     r := gin.Default()
7.     r.GET("/test", TestHandler)
8.     r.Run(":9898")
9. }

复制代码

3. r.Run()

r.Run() 接收运行时使用的端口，这里传入的是 :9898，表示运行在 9898 端口。
如果不传入参数，默认使用 8080 端口。
Run() 还返回一个 err 参数，表示运行时 error：

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

复制代码

3、接口返回参数

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

1. 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 作为返回值。

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

复制代码

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

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

1. type H map[string]any

复制代码

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

1. type TestResponse struct {
2.     Code    int    `json:"code"`
3.     Message string `json:"message"`
4. }
6. func TestHandler(c *gin.Context) {
7.     response := TestResponse{
8.         Code:    0,
9.         Message: "success",
10.     }
11.     c.JSON(http.StatusOK, response)
12. }

复制代码

4、运行模式

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

1. const (
2.     // DebugMode indicates gin mode is debug.
3.     DebugMode = "debug"
4.     // ReleaseMode indicates gin mode is release.
5.     ReleaseMode = "release"
6.     // TestMode indicates gin mode is test.
7.     TestMode = "test"
8. )

复制代码

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

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

复制代码

会输出当前的运行模式，可以访问的接口等信息，这里第一行的输出还介绍了我们使用的 r := gin.Default() 会默认使用  Logger and Recovery 两个中间件，这个后面在介绍 gin.Engine 的再详细介绍。
而如果我们设置运行模式为 release 模式，控制台仅仅会在访问接口的时候输出一条访问信息，包括访问时间、耗时、请求方式和访问的接口名称：

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

复制代码

设置运行模式

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

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

复制代码

gin 在运行时，会先加载系统环境变量 GIN_MODE，然后根据获取的值将系统设置为对应的模式。
所以我们在部署系统时，如果是以 Docker 形式部署，可以设置此变量来设置对应的运行模式。

1. declare -x GIN_MODE="release"

复制代码

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

1. gin.SetMode(gin.ReleaseMode)

复制代码

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

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！