本文首發(fā)于公眾號(hào)：Hunter后端

原文鏈接：Gin筆記一之項(xiàng)目建立與運(yùn)行

本篇筆記開始介紹 Golang 的 web 框架 Gin 的相關(guān)內(nèi)容。

本系列筆記預(yù)計(jì)通過四到五篇筆記內(nèi)容介紹 Gin 框架的核心內(nèi)容，然后通過一個(gè)簡(jiǎn)單的示例介紹一個(gè) Gin 項(xiàng)目的目錄結(jié)構(gòu)，然后介紹如何將一個(gè) Gin 項(xiàng)目使用 Docker 打包部署。

此外，還將介紹在 Gin 項(xiàng)目里連接使用 Redis、Mongo、MySQL 等操作。

以下是本篇筆記內(nèi)容：

1. 模塊安裝
2. 項(xiàng)目運(yùn)行
3. 接口返回參數(shù)
4. 運(yùn)行模式

1、模塊安裝

創(chuàng)建一個(gè)文件夾 gin_proj，然后進(jìn)入該文件夾執(zhí)行 go mod init gin_proj 初始化 Go 模塊。

然后安裝 gin 模塊：

go get github.com/gin-gonic/gin

2、項(xiàng)目運(yùn)行

我們?cè)?gin_proj 文件夾下創(chuàng)建一個(gè) main.go 文件，然后定義一個(gè)接口，然后返回?cái)?shù)據(jù)的代碼如下：

package main

import (
    "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 就可以看到對(duì)應(yīng)的結(jié)果輸出。

其代碼釋義如下。

1. gin.Default()

gin.Default() 返回的類型是 *gin.Engine，我們可以用其定義路由和分組，設(shè)置 HTTP 請(qǐng)求類型，比如這里的 r.GET() 以及后面將要介紹的路由組。

2. r.GET()

r.GET() 用于設(shè)置請(qǐng)求的方式，比如這里是 GET 請(qǐng)求，如果是 post 請(qǐng)求可以使用 r.POST()。

GET() 方法接收兩個(gè)參數(shù)，第一個(gè)參數(shù)是路由，比如這里是 /test，第二個(gè)參數(shù)是個(gè)可變參數(shù)，...HandlerFunc，可接收多個(gè) HandlerFunc 類型，此類型是一個(gè)函數(shù)，接收 *gin.Context 參數(shù)，其定義如下：

type HandlerFunc func(*Context)

這里的第二個(gè)參數(shù)，除了路由的處理函數(shù)，我們還可以在其中加上中間件處理。

在上面的代碼示例中，第二個(gè)參數(shù)用的是匿名函數(shù)，我們還可以直接將這個(gè)函數(shù)提出去：

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() 接收運(yùn)行時(shí)使用的端口，這里傳入的是 :9898，表示運(yùn)行在 9898 端口。

如果不傳入?yún)?shù)，默認(rèn)使用 8080 端口。

Run() 還返回一個(gè) err 參數(shù)，表示運(yùn)行時(shí) error：

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

3、接口返回參數(shù)

在上面 TestHandler 函數(shù)中，接收的參數(shù)是 *gin.Context，我們可以使用其處理請(qǐng)求流程，獲取請(qǐng)求數(shù)據(jù)，處理響應(yīng)，上下文數(shù)據(jù)傳遞等，這個(gè)在后面做具體的介紹。

這里返回的代碼如下：

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

1. c.JSON()

c.JSON() 這里返回的是 /test 接口的內(nèi)容，接收兩個(gè)參數(shù)，第一個(gè)是狀態(tài)碼，也就是 HTTP 狀態(tài)碼，比如 200、404 這種。

第二個(gè)參數(shù)的類型是 any，接收任意類型的數(shù)據(jù)，我們這里返回的是 gin.H{}，這個(gè)在后面再介紹。

這里的 c.JSON() 是用于向客戶端返回 json 格式的數(shù)據(jù)，會(huì)將第二個(gè)參數(shù)序列化后返回。

除了 c.JSON() 外，我們還可以使用 c.String() 返回純文本，c.HTML() 返回 HTML 頁面，和其他的 c.File() 返回文件等操作。

2. http.StatusOK

http.StatusOK 是 net/http 模塊下表示 HTTP 狀態(tài)碼的常量，其值為 200，在 c.JSON()，我們也可以直接使用 200 作為返回值。

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

除了 http.StatusOK，還有其他 2xx，3xx，4xx，5xx 等狀態(tài)碼在該模塊下都有定義，這里就不贅述了。

3. gin.H{}

gin.H 類型是一個(gè) map，其定義如下：

type H map[string]any

除了像上面一個(gè)對(duì)返回的字段挨個(gè)進(jìn)行賦值，我們還可以直接返回一個(gè) 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、運(yùn)行模式

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"
)

系統(tǒng)默認(rèn)運(yùn)行模式是 debug 模式，當(dāng)我們直接運(yùn)行 go run main.go 時(shí)，其輸出信息如下：

[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

會(huì)輸出當(dāng)前的運(yùn)行模式，可以訪問的接口等信息，這里第一行的輸出還介紹了我們使用的 r := gin.Default() 會(huì)默認(rèn)使用 Logger and Recovery 兩個(gè)中間件，這個(gè)后面在介紹 gin.Engine 的再詳細(xì)介紹。

而如果我們?cè)O(shè)置運(yùn)行模式為 release 模式，控制臺(tái)僅僅會(huì)在訪問接口的時(shí)候輸出一條訪問信息，包括訪問時(shí)間、耗時(shí)、請(qǐng)求方式和訪問的接口名稱：

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

設(shè)置運(yùn)行模式

我們可以通過下面的方法獲取和設(shè)置運(yùn)行模式：

// 獲取運(yùn)行模式
gin.Mode()

// 設(shè)置運(yùn)行模式
gin.SetMode(gin.ReleaseMode)

gin 在運(yùn)行時(shí)，會(huì)先加載系統(tǒng)環(huán)境變量 GIN_MODE，然后根據(jù)獲取的值將系統(tǒng)設(shè)置為對(duì)應(yīng)的模式。

所以我們?cè)诓渴鹣到y(tǒng)時(shí)，如果是以 Docker 形式部署，可以設(shè)置此變量來設(shè)置對(duì)應(yīng)的運(yùn)行模式。

declare -x GIN_MODE="release"

也可以在 main.go 中直接設(shè)置：

gin.SetMode(gin.ReleaseMode)

以上就是本篇筆記全部?jī)?nèi)容，主要介紹了 gin 框架的運(yùn)行方式，并介紹了一個(gè)簡(jiǎn)單示例如何設(shè)置接口并返回，還有 gin 的系統(tǒng)模式設(shè)置，接下來幾篇筆記將詳細(xì)介紹 gin.Engine 與路由的相關(guān)操作，gin.Context 與響應(yīng)處理，中間件等設(shè)置。