本文首發於公眾號：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/gin2、項目運行
我們在 gin_proj 文件夾下創建一個 main.go 文件，然後定義一個接口，然後返回數據的代碼如下：
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 就可以看到對應的結果輸出。
其代碼釋義如下。
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 與響應處理，中間件等設置。
