5.9 KiB
5.9 KiB
技术栈(Tech Stack)
"用什么"的统一速查表。选型与理由在此集中维护;"怎么把它们搭起来"见 架构设计。 未定项必须标为待定,不要让 agent 在代码里自行决定。
一、技术栈一览
| 维度 | 选型 | 状态 | 理由 / 说明 |
|---|---|---|---|
| 语言 | Go | 已定 | 网络、并发、校验、单二进制交付、可测试性强 |
| UI 框架 | Gio(纯 Go 立即模式 GUI) | 已定 | 无 CGO、单 EXE、跨版本可锁定;仅限 UI 层 |
| 现代版工具链 | Go 1.25(锁定已验证版本) + Gio v0.10.1 | 已定 | 当前受支持工具链;支持 Win10/Win11 x64 |
| Win7 版工具链 | Go 1.20.14(最终补丁) + Gio v0.6.0 | 已定 | Go 1.20 是最后支持 Win7 的版本;Gio v0.6.0 可由 Go 1.20 构建 |
| 模块结构 | 两个 go.work + 三个 go.mod(core / app-modern / app-win7) | 已定 | 根 workspace 只含 modern/core;嵌套 Win7 workspace 只含 win7/core |
| 依赖管理 | 版本锁定 + vendor(Gio 及相关依赖) | 已定 | 防止 Win7 构建被隐式升级到要求 Go 1.21+ 的依赖 |
| 存储 | JSON 文件 + 临时文件原子替换 | 已定 | 数百款软件规模足够;SQLite 仅在历史/搜索/事务需求出现后评估 |
| 软件包格式 | ZIP(标准软件包协议 v1) | 已定 | 避免 UnRAR.dll;协议见 api.md |
| 清单/许可证签名 | Ed25519(客户端只内置公钥) | 已定 | 离线可验证;私钥不进客户端与仓库 |
| 包完整性 | SHA-256 | 已定 | 下载后、执行前强制校验 |
| 传输 | HTTPS | 已定 | 清单与软件包一律 HTTPS |
| Windows API | golang.org/x/sys/windows + 动态加载(LoadLibrary) | 已定 | Win10 专属 API 动态加载并降级,不进导入表 |
| EXE 签名 | Authenticode | 已定 | 主程序与 Updater 均签名;证书采购待确认；当前本地自更新只做受限切换，不消费在线签名包 |
| 测试 | go test(core 无头可测) + fake/stub 注入 | 已定 | domain/application 不依赖 Gio 与 Windows API |
| CI | Gitea Actions 模板 + 本地 Phase 0 脚本 | 部分已定 | .gitea/workflows/phase0-build.yml 复用本地入口;远端 runner 可用性待确认 |
| 静态检查 | go vet(+ 待定 golangci-lint) | 部分已定 | vet 必跑;lint 工具后续确认 |
二、决策记录与演进
- 双版本策略:不维护两个长期开发分支;一个 main 主分支 + 共享 core + 两个 go.mod + 两个更新通道。仅当 Win7 版冻结、只接受严重修复时,才考虑建立
release/win7-legacy维护分支。 - core 兼容基线:core 保持 Go 1.20 语法和依赖兼容,使两个版本复用同一业务实现;现代版可用新 Gio 和现代 Windows 能力,但这些依赖不得反向进入 core。
- 存储:现在选择 JSON + 原子写入,避免早期引入 SQLite 的复杂度;在出现历史记录、全文搜索、大量事务需求时再评估。
- 软件包:现在只支持 ZIP;不在 v1 开放任意安装脚本(install.bat/PowerShell 钩子),未来如需运行库安装,走受审核的 prerequisites 声明。
- 授权:不复用旧盒子的 MD5/SHA-1 隐藏常量注册码设计;采用服务端 Ed25519 签名许可证 + machine_hash 绑定。
- Win7 x86:默认不提供;仅在真实用户占比支撑时增加 win7-386 构建目标。
三、构建与运行命令
工程骨架由 T-001 建立;根目录
init.sh/init.ps1统一执行依赖同步与 core 基础验证,并打印双目标构建命令。
| 用途 | 命令 |
|---|---|
| Phase 0 完整闸门(Unix) | bash scripts/verify_phase0.sh |
| Phase 0 完整闸门(Windows) | ./scripts/verify_phase0.ps1 |
| 同步根 workspace | GOTOOLCHAIN=go1.25.0 GOWORK=<repo>/go.work go work sync |
| 同步 Win7 workspace | GOTOOLCHAIN=go1.25.0 GOWORK=<repo>/app-win7/go.work go work sync(同步元数据后仍由 Go 1.20.14 校验/构建) |
| core 测试 | cd core && go test -count=1 ./... |
| core 静态检查 | cd core && go vet ./... |
| 现代版构建 | GOTOOLCHAIN=go1.25.0 GOWORK=<repo>/go.work CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go -C app-modern build -trimpath -ldflags="-H=windowsgui" -o ../dist/SoftBox.exe ./cmd/softbox |
| Win7 版构建 | GOTOOLCHAIN=go1.20.14 GOWORK=<repo>/app-win7/go.work CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go -C app-win7 build -trimpath -ldflags="-H=windowsgui" -o ../dist/SoftBox-win7.exe ./cmd/softbox |
| 本地运行(开发) | Windows 下直接 go run ./cmd/softbox(WSL 中构建 EXE 后到 Windows 侧运行) |
根 go.work 使用 Go 1.25.0,只纳入 app-modern 与 core;app-win7/go.work 使用 Go 1.20,只纳入 app-win7 与 core。同步、测试和构建始终显式指定对应 GOWORK,任何 workspace 都不会同时解析 Gio v0.10.1 与 v0.6.0。
两个 workspace 的元数据同步统一使用 Go 1.25.0。原因是 Go 1.20.14 的 go work sync 会忽略 workspace 级本地 replace 并尝试联网解析占位模块 softbox.local/core@v0.0.0;不为规避该工具缺陷把本机相对路径写进 go.mod。Win7 的依赖图、测试和构建仍全部强制使用 Go 1.20.14,并由版本检查拒绝 Go 1.21+ 依赖。
工具链矩阵:
| 构建目标 | 工具链 | Gio | 支持系统 | 维护策略 |
|---|---|---|---|---|
| modern-amd64 | Go 1.25(锁定) | v0.10.1 | Win10/Win11 x64 | 正常新增功能 |
| win7-amd64 | Go 1.20.14 | v0.6.0 | Win7 SP1 x64 及更高 | 兼容与严重修复 |
| win7-386 | Go 1.20.14 | v0.6.0 | Win7 SP1 x86 及更高 | 仅真实需求时提供 |
四、依赖纪律
- 新增第三方依赖前,先说明用途、替代方案和维护成本,并确认其 go.mod 的
go指令不超过对应模块的工具链基线(core 与 app-win7 为 1.20)。 - core 禁止依赖 Gio、SQLite 驱动、Windows 专属包;平台能力一律接口注入。
- Gio 及 UI 相关依赖锁定版本并 vendor;升级 Gio 只允许在 app-modern,且需单独任务评估。
- 不确定的技术选型先更新本文,再进入代码。
- 不允许同一职责并存两套实现(如两套下载器、两套配置读写)。