Wailsv2+Go+Vue3桌面脚手架实战，用CI检查固化工程约定

在软件开发中，项目基座的构建往往被视为一项基础但关键的工作。然而，许多团队在搭建完初始框架后，很快就会发现原本清晰的工程规范逐渐被忽视甚至废弃。这种"软约束"失效的现象，在 AI 辅助代码生成日益普及的今天尤为突出——机器不会阅读文档中的规则，只会选择最便捷的实现路径。

基于这一痛点，本文以 Wails v2 + Go + Vue3 桌面脚手架的开发为例，分享如何将工程约定转化为可自动验证的 CI 检查。这个脚手架的核心价值不在于几千行代码本身，而在于"把工程约定变成 CI 里会失败的检查"这一方法论。这种方法不仅适用于当前技术栈，其原理同样可以迁移到其他桌面应用开发框架（如 Tauri）。

技术选型：为何选择 Wails

在选择技术栈时，我们主要考虑了三个维度：包体大小、后端语言支持以及跨平台通信效率。与 Electron 打包 Chromium 动辄上百兆不同，Wails 利用系统自带的 WebView（macOS 使用 WKWebView，Windows 使用 WebView2），最终产物通常只有几 MB。此外，Go 语言在处理本地文件读写、SQLite 数据库操作以及系统集成方面具有显著优势，这使得它成为构建"真桌面程序"的理想选择。在通信机制上，Wails 提供了零成本的绑定方法，无需手动编写 IPC 协议或启动 HTTP 服务。

尽管如此，Wails 也存在一些局限性，例如生态成熟度和调试体验不如 Electron，部分系统能力在 Wails v2 中仍存在坑点。不过，这些代价在我们的场景下是可以接受的，因为我们更关注的是快速构建功能完备的桌面应用。

架构设计：分层与边界验证

该脚手架采用了朴素但严谨的分层架构设计，每一层的边界都通过机器验证来确保规范执行。具体来说，架构分为四个核心层级：

• frontend/src/lib：前端侧的契约常量，包括 invoke、event 和 page 的定义
• app.go：绑定方法层，提供前端可以直接调用的 Go 方法，且不直接操作数据库
• internal/service：业务逻辑层，负责真正的 CRUD 操作，可以访问数据库
• internal/model：数据模型层，作为叶子节点，不允许导入任何其他层的内容

为了确保这些分层边界的严格执行，我们引入了一个名为 internal/guard 的模块。这个模块通过 go/test 的形式运行，在 make test 时自动检查代码是否符合预设的规范。例如，绑定方法层不应直接访问数据库，service 层不应导入 frontend 相关代码等。这种自动化检查机制的关键在于：当解析到 0 个结果时必须报错，而不是静默通过，从而避免护栏"瞎掉"的情况发生。

核心实现：AST 解析与结构化断言

// 关键：找不到目标文件 → 报错，而不是"跳过这项检查"

这段代码首先解析项目根目录下的所有文件，然后检查绑定方法层是否直接导入了数据库相关的依赖。如果发现违规，测试将立即失败并给出明确的错误信息。这种基于 AST 解析的方法能够精确地识别代码结构变化，并及时反馈给开发者。

实践效果与思考

通过这种方式，我们成功地将工程规范从"软约束"转变为"硬检查"。在实际开发过程中，这种自动化验证机制带来了显著的好处：

总的来说，这种方法不仅提升了项目的可维护性和可靠性，也为团队建立了一套可持续的工程治理机制。虽然实现过程需要一定的前期投入，但长期来看，这种"约定即检查"的理念能够显著降低技术债务，提高开发效率。

图1展示了 Wails 脚手架的核心架构分层，包括前端契约、绑定方法层、业务服务层和数据模型层，清晰地体现了各层之间的依赖关系和边界控制

图2展示了 Go 语言的标志，强调了本项目后端采用 Go 语言的事实，以及其在构建高性能桌面应用方面的优势