Wails v2+Go+Vue3:将架构约定编译成自动化测试的脚手架
最近有个朋友扔给我一个问题:你的桌面项目怎么做到半年之后改代码还能不心惊胆战?我说,因为我其实不太信任人,更信任测试。这不是一句鸡汤,我是真的把一个新项目的架构约定全部写成了测试,约定一旦被破坏,我不用等人提醒,测试直接在终端里给我变红。这里的关键词是 Wails v2、Go、Vue3,再加上一点点对“代码会腐烂”的厌恶感。
Wails v2 是我近期体验过最适合做内部工具和个人生产力软件的桌面方案之一。它用 Go 写后端逻辑,用 Vue3 写界面,最终打包出来的是一个体积可控的原生窗口程序。比起 Electron 动辄一两百兆的体积,Wails 打完包通常只有二十到五十兆;比起 Tauri 那套 Rust 链路,Wails 对 Go 背景的团队又友好太多。但熟悉它的人都知道,Wails 最危险的地方恰恰在于“前后端之间太自由了”:前端可以通过 window.go 直接调用后端绑定的任意方法,后端也可以把任何逻辑塞进一个 App 结构体里。项目一开始很爽,几周之后就变成一锅粥。
所以我搭了一个脚手架,把架构约定从“代码评审时要靠嘴提醒”变成了“跑测试时直接报红”。这篇文章完整记录这套方案:Wails v2 + Go + Vue3 桌面脚手架怎么搭、架构约定怎么写、如何把这些约定编译成会变红的测试,以及我实际踩过的一些坑。不管你是在评估 Wails、正在用 Wails,还是想在任意技术栈里复制这套“约定即测试”的思路,都值得往下看。
1. 整体设计思路拆解:为什么要把架构约定“测试化”
1.1 先想清楚:脚手架到底要解决什么问题
脚手架不是把 wails init 跑一遍就完了。如果只是生成官方模板,那叫做模板,不叫脚手架。脚手架的核心价值,是让团队里每个人拿到项目之后,按照同一种方式写代码,并且不依赖“资深同事盯着你”。
我见过太多项目死在同一个地方:前期约定得好好的,比如“控制器里不要直接查数据库”“前端不要在组件里直接调用后端接口”,但一到赶进度的时候,谁还会记得这种口头约定?等发现的时候,代码已经长成一大坨。后来我意识到,架构约定如果没办法被机器检查,那它就只是一句口号。口号是不能保证质量的。
所以这个脚手架的第二个核心功能,是一组“架构测试”。它不是测某个业务函数返回什么,而是检查代码结构本身:哪个包可以依赖哪个包、哪个目录不允许出现什么代码、前端调用后端的唯一入口在哪里。这些测试会像单测一样跑在 CI 里,也会在每次本地编译前被触发。谁违反了约定,谁就面对一片红。
1.2 为什么选 Go + Vue3 这对组合
先说 Go。Wails v2 的后端完全走 Go,和 CGO 的交互被封装得很好,开发时我不需要关心平台相关的窗口 API。Go 的编译速度、部署形态和静态类型系统,也正好适合做“带复杂后台逻辑的桌面工具”。尤其是有文件系统操作、数据库、调用本地命令这类需求时,Go 写起来比前端舒服太多。
再说 Vue3。Vue3 的响应式模型和组合式 API 让界面代码很有条理。搭配 Vite 做开发服务器,热更新速度快,组件组织起来也顺手。Wails 官方模板里有一个很不错的 Vue3 起点,但默认结构其实带着“演示项目”的气质:只有一个 App 组件和一个 greeting 方法绑定。如果直接在这上面堆业务,必然会堆出事故。所以我做脚手架的第一步,就是先把官方模板这副“散装骨架”理成有边界的结构。
1.3 “编译成测试”到底是什么意思
说起来也简单:把架构约定写成代码,让代码去检查代码。
Go 这边有一个特别适合干这事的核心武器:标准库 go/ast。它能解析 Go 源码成抽象语法树,我可以遍历每个文件的 import 声明、函数调用、类型定义,再结合文件所在的目录来判断有没有越界。
Vue3 前端这边则用 Node 脚本做静态扫描。因为前端约定大多是调用边界和命名习惯,不需要深度语法分析,用正则和路径匹配就能覆盖,简单直接,反而更稳定。
这套东西运行起来的体验就是:你写完一版代码,跑一下 make build 或者 go test ./...,如果某个模块违反约定,终端里会明确提示“某某文件不应导入某某包”。红线不是靠人嘴说出来的,是测试亮出来的。
2. 核心细节解析:目录划分与前后端边界
2.1 后端目录的“四层结构”
Wails v2 官方初始化的思路是:根目录放 main.go 和 app.go,前端打包后在 frontend/dist,通过 wails.json 指定。这在演示项目里合适,但真实项目不能这么摊大饼。我把它改造成一个很朴素但有效的四层结构:
从名字就能看出来,分层的方向是 handler → service → repository → 外部基础设施,而 domain 是所有人都可以引用的底层模型层。
为什么要这么分?因为这四层各有职责。handler 在 Wails 里就是绑定给前端的方法集合,它只做参数接收、调用 service、把结果返回;service 写业务规则、组合多个数据源;repository 负责持久化,无论是 SQLite、本地文件还是远程接口,都被它包起来;domain 则是纯粹的实体和值对象,不应该依赖任何内部层。这个分层不新鲜,但它能救命的点是:如果没有测试强制,第四周就会出现 handler 顺手查了个库、service 里写了一坨 IO 代码的乱象。
2.2 前端调用后端的“唯一入口”
Wails v2 会向前端注入一个全局对象,默认情况下,你可以在 Vue3 组件里直接写 window.go.backend.App.Greet() 之类的调用。这看起来方便,后果却很糟糕:以后想换掉某个后端方法、想加一层参数校验或者统一错误处理,都得满项目搜 window.go。
我的约定是:所有对后端对象的访问,只允许出现在 frontend/src/api 目录下的模块里。组件和页面只能 import 这个目录里的业务方法,不允许直接触碰 window.go。
结构长这样:
api/todo.ts 里封装的是具体方法: