本文首发于公众号:Hunter后端
原文链接:Gin笔记一之项目建立与运行
本篇笔记开始介绍 Golang
的 web
框架 Gin
的相关内容。
本系列笔记预计通过四到五篇笔记内容介绍 Gin
框架的核心内容,然后通过一个简单的示例介绍一个 Gin
项目的目录结构,然后介绍如何将一个 Gin
项目使用 Docker
打包部署。
此外,还将介绍在 Gin
项目里连接使用 Redis
、Mongo
、MySQL
等操作。
以下是本篇笔记内容:
- 模块安装
- 项目运行
- 接口返回参数
- 运行模式
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
与响应处理,中间件等设置。