Wails v3 集成 Gin 实现自定义路由Gin-Routing 示例深度解析【免费下载链接】wailsCreate beautiful applications using Go项目地址: https://gitcode.com/gh_mirrors/wa/wails本指南以仓库中 gin-routing 示例 为骨架完整讲解如何在 Wails v3 应用中把 Gin 作为核心路由引擎与资产处理器Asset Handler并通过中间件在 Wails 内建处理与 Gin 路由之间灵活分流。读完本文你将掌握 Gin 路由挂载、Wails 中间件分流机制、/wails运行时路由保护、Go 与前端事件双向通信的完整实战方案。示例概览为什么要用 Gin 做路由Wails v3 默认使用内置的 AssetServer 提供静态资源并通过/wails/runtime.js暴露运行时 API。但在复杂业务中你可能需要在桌面应用内部实现 RESTful API如/api/hello让 WebView 加载的页面路由由 Go 侧统一控制复用 Gin 生态中成熟的中间件日志、鉴权、CORS、限流等。v3/examples/gin-routing示例正是为此设计的。它演示了 5 个核心能力将 Gin 引擎挂载为 Wails 应用的资产处理器Asset Handler编写 Wails 中间件把请求在 Wails 与 Gin 之间按路径分发用 Gin 定义 API 端点并返回 JSON让 Gin 托管的前端页面与 Wails 后端通过事件机制通信自定义 Gin 中间件请求日志。快速运行示例进入示例目录拉取依赖后直接运行cd v3/examples/gin-routing go mod tidy go run .启动后会出现一个 900×700 的窗口标题为 Wails Gin Example其首页即由 Gin 的/路由渲染。go.mod中通过replace github.com/wailsapp/wails/v3 ../..将 Wails v3 指向仓库本地的 v3 源码便于随主仓库同步调试。架构拆解请求如何在 Wails 与 Gin 之间分流整个示例的核心是Wails 层中间件application.Middleware Gin 层路由的两级体系请求流程如下WebView 发起请求 │ ▼ Wails AssetServer 中间件链 │ ├─ 路径以 /wails 开头──► 交给 Wails 内置处理器runtime.js 等 │ └─ 其余路径 ──► 交给 Gin 引擎 │ ├─ /static/* ──► 内嵌静态文件 ├─ / ──► 首页 HTML └─ /api/hello ──► JSON APIWails 侧分流中间件GinMiddleware源码位于 main.go// GinMiddleware creates a middleware that passes requests to Gin if theyre 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) }) } }关键设计点/wails前缀必须放行前端页面通过import * as wails from /wails/runtime.js加载运行时若将该请求也交给 Gin运行时将不可用事件通信和 Go 调用会全部失效next.ServeHTTP触发 Wails 内建链路在 application.go 中可以看到 Wails 自身拦截了/wails/runtime.js、/wails/transport.js等内置路径并提供实现这些正是示例中间件放行的对象其余请求全部转交 GinginEngine.ServeHTTP(w, r)直接复用标准http.Handler接口因此中间件实现极度简洁且与 Wails 的中间件类型天然兼容。Wails 中间件类型与链式组合从 application_options.go 可以看出application.Middleware的本质是一个标准 HTTP 包装函数type Middleware func(next http.Handler) http.HandlerWails 还提供了ChainMiddleware(middleware ...Middleware) Middleware允许把多个中间件反向链式组合成一个。这意味着你可以在GinMiddleware之外再叠加鉴权、日志、流量控制等任意标准 HTTP 中间件而不必修改 Gin 本身。资产处理器配置AssetOptions在创建应用时示例把 Gin 引擎同时设置为Handler与Middlewaremain.goapp : 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), }, })对照 application_options.go 的字段定义字段作用本示例取值Handler http.Handler向 WebView 提供全部内容的处理器ginEngineMiddleware Middleware挂钩到 AssetServer 请求链可动态跳过默认处理器以支持自定义路由GinMiddleware(ginEngine)DisableLogging bool关闭 AssetServer 请求日志默认记录每个请求未设置官方注释特别说明该 Middleware 注入在 Wails 内部中间件之前且接收到的next就是 AssetServer 的默认处理器——这正是示例中放行/wails、其余交给 Gin的机制来源。若未定义 Middleware则执行默认请求链即用Handler提供资源。Gin 侧路由与中间件使用 gin.New() 而非 gin.Default()ginEngine : gin.New() // Using New() instead of Default() to add our own middleware ginEngine.Use(gin.Recovery()) ginEngine.Use(LoggingMiddleware())gin.Default()会自动挂载 Logger 与 Recovery而这里为了演示自定义日志中间件改用gin.New()后手动挂载gin.Recovery()兜底 panic 恢复防止单个请求崩溃拖垮整个应用LoggingMiddleware()示例自定义中间件见 main.go。自定义日志中间件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, ) } }它演示了 Gin 中间件的标准写法c.Next()之前记录起始时间之后计算耗时并输出方法、路径、客户端 IP、状态码与延迟产出一条带[GIN]前缀的结构化日志。这套模式可以平滑扩展为鉴权在c.Next()前校验并c.Abort()等业务中间件。静态文件与 API 端点// Serve embedded static files ginEngine.StaticFS(/static, http.FS(staticFiles)) // Define routes ginEngine.GET(/, func(c *gin.Context) { file, err : staticFiles.ReadFile(static/index.html) if err ! nil { c.String(http.StatusInternalServerError, Error reading index.html) return } c.Data(http.StatusOK, text/html; charsetutf-8, file) }) 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), }) })前端资源通过//go:embed static编译进二进制main.go/static由StaticFS提供无需外部文件/路由从内嵌 FS 中读取并渲染首页/api/hello返回 JSON消息 RFC3339 时间戳作为前端fetch调用的演示端点。前端与 Wails 后端的双向通信页面通过 Gin 提供运行时仍来自 Wailsstatic/index.html 虽然由 Gin 渲染但运行时模块依然从 Wails 加载script typemodule import * as wails from /wails/runtime.js; ...由于分流中间件放行了/wails前缀该 import 能命中 Wails 的内置运行时实现进而使用wails.Events.Emit向 Go 侧发事件。前端发事件 → Go 侧监听点击 Trigger Event 按钮会执行await wails.Events.Emit(gin-button-clicked, Hello from Gin!);Go 侧在 main.go 注册同名监听器app.Event.On(gin-button-clicked, func(event *application.CustomEvent) { log.Printf(Received event from frontend: %v, event.Data) })CustomEvent定义于 events.go包含Name事件名、Data任意载荷、Sender发送方窗口应用级发送时为空等字段并支持Cancel()/IsCancelled()进行事件级取消控制。这意味着你完全可以把任意 JSON 数据表单、操作指令、文件内容从前端透传到 Go 侧。前端调 API → Gin 返回 JSON点击 Call API 按钮会fetch(/api/hello)并渲染返回的 JSON——这条请求链完全发生在 HTTP 层WebView → Wails 分流中间件 → Gin/api/hello→ JSON 响应无需任何桥接代码充分体现了API 即 HTTP的简洁性。窗口创建与应用生命周期app.Window.NewWithOptions(application.WebviewWindowOptions{ Title: Wails Gin Example, Width: 900, Height: 700, URL: /, }) err : app.Run() if err ! nil { log.Fatal(err) }URL: /让窗口首屏直接命中 Gin 的/路由app.Run()启动事件循环Mac.ApplicationShouldTerminateAfterLastWindowClosed保证 macOS 下关闭窗口即退出进程。扩展思路把该模式移植到自己的项目从源码结构看这套方案具备很强的可移植性可按以下步骤落地将GinMiddleware复制到自己的项目保留/wails前缀放行逻辑在AssetOptions中设置Handler: ginEngine, Middleware: GinMiddleware(ginEngine)用ginEngine.StaticFS或Static挂载前端构建产物如dist/按需补充业务路由/api/*与 Gin 中间件鉴权、CORS、限流前端继续从/wails/runtime.js引入运行时保持与 Wails 的桥接能力。需要同时接入多个 HTTP 层时可结合ChainMiddleware将 Wails 中间件串行组合若希望 WebSocket 等高级能力也由 Gin 接管可在中间件内按路径做更细粒度的分发。小结gin-routing示例给出了一个干净、可复用的Wails 前端 Gin 后端路由集成范式Wails 负责窗口与运行时桥接Gin 负责页面与 API 路由二者通过一个 10 行左右的application.Middleware完成无缝分流。对需要复杂路由、REST API 或复用 Gin 生态中间件的 Wails v3 应用而言这是开箱即用的参考实现。【免费下载链接】wailsCreate beautiful applications using Go项目地址: https://gitcode.com/gh_mirrors/wa/wails创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考