本文首發于公眾號：Hunter后端

原文鏈接：Gin筆記二之gin.Engine和路由設置

這一篇筆記主要介紹 gin.Engine，設置路由等操作，以下是本篇筆記目錄：

1. gin.Default() 和 gin.New()
2. HTTP 方法
3. 路由分組與中間件

1、gin.Default() 和 gin.New()

前面第一篇筆記介紹，創建一個 gin 的路由引擎使用的函數是 gin.Default()，返回的類型是 *gin.Engine，我們可以使用其創建路由和路由組。

除了這個函數外，還有一個 gin.New()，其返回的也是 *gin.Engine，但是不一樣的是 gin.Default() 會對 gin.Engine 添加默認的 Logger() 和 Recovery() 中間件。

這兩個函數大致內容如下：

func New(opts ...OptionFunc) *Engine {
    ...
}

func Default(opts ...OptionFunc) *Engine {
    ...
    engine := New()
    engine.Use(Logger(), Recovery())
    ...
}

我們使用第一篇筆記中使用 debug 模式運行系統后輸出的信息可以再看一下：

[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

我們使用的是 gin.Default() 運行的系統，所以在第一行告訴我們創建了一個帶有 Logger and Recovery 中間件的 Engine。

同時第三行輸出路由信息的地方，標明了這個路由指向的處理函數，后面的括號里是 3 handlers，這個意思是除了我們處理路由的 handler，還有兩個默認的中間件 handler，也就是這里的 Logger() 和 Recovery() 中間件。

下面介紹一下 Logger() 和 Recovery() 這兩個 handler 的作用。

1. Logger()

默認的 Logger() 會輸出接口調用的信息，比如第一篇中我們定義了一個 /test 接口，當我們調用這個接口的時候，控制臺會輸出下面這條信息：

[GIN] 2025/08/19 - 23:15:26 | 200 |      36.666μs |       127.0.0.1 | GET      "/test"

可以看到日志中會包含請求時間、返回的 HTTP 狀態碼、請求耗時、調用方 ip、請求方式和接口名稱等。

這條日志信息的輸出就是 Logger() 這個中間件起的作用。

在其內部，會調用一個 LoggerWithConfig() 函數，獲取到請求的 ip、記錄調用時間、調用方式等信息，然后進行輸出，下面是部分源碼信息：

param.TimeStamp = time.Now()
param.Latency = param.TimeStamp.Sub(start)

param.ClientIP = c.ClientIP()
param.Method = c.Request.Method
param.StatusCode = c.Writer.Status()
param.ErrorMessage = c.Errors.ByType(ErrorTypePrivate).String()

2. Recovery()

Recovery() 中間件則可以為我們捕獲程序中未處理的 panic，記錄錯誤信息并返回 500 狀態碼信息，比如我們在第一篇筆記中使用的 TestHandler 函數，我們在其中加一個除數為 0 的錯誤：

func TestHandler(c *gin.Context) {
    response := TestResponse{
        Code:    0,
        Message: "success",
    }
    a := 0
    fmt.Println(1 / a)
    c.JSON(http.StatusOK, response)
}

在接口調用的時候，如果我們使用的是 gin.Default()，那么客戶端不會報錯，而是會收到一個 HTTP 狀態碼為 500 的報錯信息，而如果使用的是 gin.New()，客戶端則會直接發生錯誤。

總的來說，Logger() 和 Recovery() 這兩個的中間件是 gin 框架為我們默認添加的對于開發者來說較為友好的兩個操作，在后面介紹中間件的時候，我們也可以手動實現這兩個功能。

2、HTTP 方法

gin.Engine 支持配置 HTTP 多個方法，比如 GET、POST、PUT、DELETE 等。

以第一篇筆記中的代碼為例，其設置方法如下：

r.GET("/test", TestHandler)
r.POST("/test", TestHandler)
r.PUT("/test", TestHandler)
r.DELETE("/test", TestHandler)

3、路由分組與中間件

除了設置單個路由，我們還可以對路由進行分組設置，比如需要控制版本，或者模塊設置需要統一的前綴，又或者是需要統一設置中間件功能的時候。

其整體代碼示例如下：

package main

import (
    "fmt"
    "net/http"
    "github.com/gin-gonic/gin"
)

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

func main() {
    r := gin.Default()

    v1 := r.Group("/v1")
    {
        v1.GET("/test", TestHandler)
    }

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

這里，我們設置了一個路由名稱以 v1 為前綴的路由組，其下每個路由的訪問都需要帶有 /v1，這樣就實現了統一設置路由前綴的功能。

而如果我們需要向其中添加中間件的時候，也可以不用挨個路由進行設置，而是在 v1 路由組的設置中就可以實現，比如：

v1 := r.Group("/v1", Middleware1, Middleware2)

這樣，其下每個路由的 handler 函數在調用前就都會先調用 Middleware1 和 Middleware2 這兩個中間件。

以上就是本篇筆記關于 gin.Engine 的全部內容，其實中間件的相關操作也應該屬于 gin.Engine 的內容，但是那部分需要介紹的知識點和想要用于介紹的代碼示例略多，所以就單獨開一篇筆記在后面再介紹。