本文首发于公众号：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 与响应处理，中间件等设置。