使用 Gin 进行路由

本指南演示如何将Gin Web 框架与 Wails v3 集成。Gin 是一个使用 Go 编写的高性能 HTTP Web 框架，可用于轻松构建 Web 应用和 API。

简介

Wails v3 提供灵活的资源系统，允许你使用任何 HTTP 处理程序，包括 Gin 等流行的 Web 框架。通过这种集成，你可以：

使用 Gin 的路由和中间件提供 Web 内容
创建可从 Wails 应用访问的 RESTful API
在保持 Wails 桌面集成的同时使用 Gin 的功能

为 Wails 设置 Gin

要将 Gin 与 Wails 集成，需要创建一个 Gin 路由器，并将其配置为 Wails 应用的资源处理程序。具体步骤如下：

1. 安装依赖项

首先，确保已安装 Gin 包：

bash

go get -u github.com/gin-gonic/gin

2. 为 Gin 创建中间件

创建一个中间件函数，用于处理 Wails 与 Gin 之间的集成：

// GinMiddleware creates a middleware that passes requests to Gin if they're not handled by Wails
func GinMiddleware(ginEngine *gin.Engine) application.Middleware {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			// Let Wails handle the `/wails` route
			if strings.HasPrefix(r.URL.Path, "/wails") {
				next.ServeHTTP(w, r)
				return
			}
			// Let Gin handle everything else
			ginEngine.ServeHTTP(w, r)
		})
	}
}

此中间件会将所有 HTTP 请求传递给 Gin 路由器。

3. 配置 Gin 路由器

为 Gin 路由器设置路由、中间件和处理程序：

// Create a new Gin router
ginEngine := gin.New() // Using New() instead of Default() to add custom middleware

// Add middlewares
ginEngine.Use(gin.Recovery())
ginEngine.Use(LoggingMiddleware()) // Your custom middleware

// Define routes
ginEngine.GET("/", func(c *gin.Context) {
    // Serve your main page
})

ginEngine.GET("/api/hello", func(c *gin.Context) {
    c.JSON(http.StatusOK, gin.H{
        "message": "Hello from Gin API!",
        "time":    time.Now().Format(time.RFC3339),
    })
})

4. 与 Wails 应用集成

将 Wails 应用配置为使用 Gin 路由器作为其资源处理程序：

// Create a new Wails application
app := application.New(application.Options{
    Name:        "Gin Example",
    Description: "A demo of using Gin with Wails",
    Mac: application.MacOptions{
        ApplicationShouldTerminateAfterLastWindowClosed: true,
    },
    Assets: application.AssetOptions{
        Handler:    ginEngine,
        Middleware: GinMiddleware(ginEngine),
    },
})

// Create window
app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title:    "Wails + Gin Example",
    Width:    900,
    Height:   700,
    URL:      "/", // This will load the route handled by Gin
})

提供静态内容

使用 Go 的embed包将静态文件嵌入二进制文件：

//go:embed static
var staticFiles embed.FS

ginEngine.StaticFS("/static", http.FS(staticFiles))
ginEngine.GET("/", func(c *gin.Context) {
    file, _ := staticFiles.ReadFile("static/index.html")
    c.Data(http.StatusOK, "text/html; charset=utf-8", file)
})

在开发环境中，使用ginEngine.Static("/static", "./static")直接从磁盘提供文件。

自定义中间件

Gin 允许你根据不同用途创建自定义中间件。以下是一个日志记录中间件示例：

// LoggingMiddleware is a Gin middleware that logs request details
func LoggingMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // Start timer
        startTime := time.Now()

        // Process request
        c.Next()

        // Calculate latency
        latency := time.Since(startTime)

        // Log request details
        log.Printf("[GIN] %s | %s | %s | %d | %s",
            c.Request.Method,
            c.Request.URL.Path,
            c.ClientIP(),
            c.Writer.Status(),
            latency,
        )
    }
}

处理 API 请求

使用 Gin 可以轻松创建 RESTful API。以下是定义 API 端点的方法：

// GET endpoint
ginEngine.GET("/api/users", func(c *gin.Context) {
    c.JSON(http.StatusOK, users)
})

// POST endpoint with JSON binding
ginEngine.POST("/api/users", func(c *gin.Context) {
    var newUser User
    if err := c.ShouldBindJSON(&newUser); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    // Process the new user...
    c.JSON(http.StatusCreated, newUser)
})

// Path parameters
ginEngine.GET("/api/users/:id", func(c *gin.Context) {
    id := c.Param("id")
    // Find user by ID...
    c.JSON(http.StatusOK, user)
})

// Query parameters
ginEngine.GET("/api/search", func(c *gin.Context) {
    query := c.DefaultQuery("q", "")
    limit := c.DefaultQuery("limit", "10")
    // Perform search...
    c.JSON(http.StatusOK, results)
})

使用 Wails 功能

由 Gin 提供的 Web 内容可以使用@wailsio/runtime包与 Wails 功能交互。

事件处理

在 Go 中注册事件处理程序：

app.Event.On("my-event", func(event *application.CustomEvent) {
    log.Printf("Received event: %v", event.Data)
})

使用运行时从 JavaScript 调用：

html

<script type="module">
    import { Events } from '@wailsio/runtime';

    Events.Emit("my-event", { message: "Hello from frontend" });
    Events.On("response-event", (data) => console.log(data));
</script>

高级配置

自定义 Gin 模式

在生产环境中将 Gin 设置为发布模式：

gin.SetMode(gin.ReleaseMode)  // Use gin.DebugMode for development
ginEngine := gin.New()

处理 WebSocket

可以使用 Gorilla WebSocket 等库将 WebSocket 与 Gin 集成：

import "github.com/gorilla/websocket"

var upgrader = websocket.Upgrader{
    ReadBufferSize:  1024,
    WriteBufferSize: 1024,
    CheckOrigin: func(r *http.Request) bool {
        return true // Allow all connections
    },
}

// In your route handler:
ginEngine.GET("/ws", func(c *gin.Context) {
    conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
    if err != nil {
        log.Println(err)
        return
    }
    defer conn.Close()
    
    // Handle WebSocket connection...
})

最佳实践

使用 Go 的 embed 包：将静态文件嵌入二进制文件，以便更好地分发。
关注点分离：将 API 逻辑与 UI 逻辑分开。
错误处理：在 Gin 路由和前端代码中都实现妥善的错误处理。
安全性：注意安全方面的事项，尤其是在处理用户输入时。
性能：在生产环境中使用 Gin 的发布模式，以获得更好的性能。
测试：使用 Gin 的测试实用工具为 Gin 路由编写测试。

总结

将 Gin 与 Wails 集成，能够充分结合二者的优势，使用 Web 技术构建桌面应用。Gin 的性能和丰富功能与 Wails 的桌面集成能力相辅相成，让你可以创建兼具二者优势的复杂应用。

有关更多信息，请参阅Gin 文档和Wails 文档。

无障碍

编辑此文档