# junx-ddd-app **Repository Path**: wangwang2020/junx-ddd-app ## Basic Information - **Project Name**: junx-ddd-app - **Description**: Junx-ddd-App是一款桌面聚合应用，采用Golang+Wails V3+Vue3编写。 - **Primary Language**: Go - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-12 - **Last Updated**: 2026-07-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # junx-ddd-app > 基于 DDD 分层架构与插件系统的**桌面应用聚合平台**。单二进制同时支持桌面（Wails v3 WebView2）与 Server（无 GUI）双运行模式，前端通过「双通道」与后端通信。 --- ## 目录 - [项目简介](#项目简介) - [功能特性](#功能特性) - [技术栈](#技术栈) - [安装说明](#安装说明) - [使用方法](#使用方法) - [目录结构说明](#目录结构说明) - [插件系统简介](#插件系统简介) - [版本信息](#版本信息) - [开源许可证声明](#开源许可证声明) --- ## 项目简介 `junx-ddd-app` 是一个用于**聚合与管理各类应用入口**的桌面平台：它把本地应用、命令应用、在线应用、前端应用统一收纳到同一个启动器里，提供收藏、最近使用、分类导航等能力。 平台的核心设计目标是**可扩展**： - 后端采用严格 DDD 分层（domain → repository → service → binding → router/server → 组装层 `app.go`），依赖只向内，便于单测与演进。 - 通过**插件系统**暴露扩展点：插件可以注册 HTTP 路由（REST）、暴露 Wails Binding（桌面双通道），或两者兼具，而无需感知 Wails / Gin / GORM 的存在。 - 前端 SPA 通过「双通道」与后端交互：桌面端走 Wails Binding，浏览器/Server 模式自动降级为 REST（`fetch`）。 --- ## 功能特性 - **四类应用统一管理** - `local` 本地应用（内置功能，如系统信息） - `command` 命令应用（调用本地命令行） - `online` 在线应用（内嵌网页） - `frontend` 前端应用（内置前端页面） - **插件化扩展**：内置 `bbsysinfo`（系统信息）、`bbcreatecmd`（批量创建命令应用）、`bbcreateonline`（批量创建在线应用）三个插件，并支持继续扩展。 - **双运行模式** - `desktop`：Wails v3 桌面窗口，WebView2 渲染前端。 - `server`：无 GUI，仅启动 HTTP API 服务，适合部署/远程访问。 - **双通道通信**：前端自动识别运行环境，桌面走 Wails Binding，浏览器降级到 REST，代码无需分支。 - **内置应用与内存缓存**：启动时注册内置应用，AppService 维护内存缓存，插件变更后通过 `NotifyAppChange` 触发重载。 - **收藏 / 最近使用 / 分类导航**：提升日常使用效率。 - **KV 配置存储**：打通桌面 Binding 与浏览器降级通道的语义。 - **多平台**：支持 Windows / macOS / Linux 构建（Wails 提供原生打包）。 --- ## 技术栈 | 层 | 技术 | | --- | --- | | 语言 | Go 1.25 | | 桌面框架 | Wails v3 (`wailsapp/wails/v3`) | | Web 框架 | Gin (`gin-gonic/gin`) | | ORM / 数据库 | GORM + SQLite（纯 Go 驱动 `glebarez/sqlite`） | | 配置 | Viper（`JUN_` 前缀环境变量覆盖） | | 日志 | Zap + lumberjack 滚动切割 | | 前端 | Vue 3 + TypeScript + Vite 8 | | 状态管理 | Pinia | | UI 组件 | Naive UI + Tailwind CSS 4 | | 包管理 | 前端 `bun` / `npm`；任务编排 `go-task` | --- ## 安装说明 ### 环境要求 - **Go** ≥ 1.25（见 `go.mod`） - **Node.js** ≥ 22（前端依赖 Vite 8），包管理器推荐 `bun`（也可用 `npm`） - **Wails v3 CLI**：`go install github.com/wailsapp/wails/v3/cmd/wails@latest` - **WebView2**（仅 Windows 桌面运行需要，通常系统已自带） - **Git** ### 获取源码 ```bash git clone junx-ddd-app cd junx-ddd-app ``` ### 安装依赖 ```bash # Go 依赖 go mod download # 前端依赖（以 bun 为例） cd frontend bun install # 或使用 npm # npm install cd .. ``` --- ## 使用方法 ### 开发模式（热重载） ```bash # 同时启动 Wails 桌面窗口 + Vite 开发服务器（默认端口 9245） task dev ``` > `task dev` 实际执行 `wails3 dev -config ./build/config.yml -port 9245`。 ### 桌面构建与运行 ```bash # 按当前系统构建桌面二进制 task build # 直接运行（开发/调试用） task run ``` ### Server 模式（无 GUI，HTTP API） ```bash # 构建 server 模式二进制（仅 HTTP 服务，不启动窗口） task build:server # 运行 server 模式，默认监听 :9246 task run:server ``` 启动后用浏览器访问 `http://localhost:9246`，前端通过 REST 通道与后端交互（可验证 `GET /api/apps` 返回 200）。 ### 配置说明 配置文件位于 `configs/config.yaml`，关键字段： ```yaml app: name: "junx-ddd-app" version: "0.1.0" database: path: "junx.db" mode: "memory" # memory 内存模式 | file 文件模式 server: port: 9246 mode: "desktop" # desktop | server logger: level: "info" # debug | info | warn | error file_path: "logs/junx.log" ``` 所有配置均可通过 **`JUN_` 前缀环境变量**覆盖（`.` 用 `_` 代替），例如： ```bash export JUN_DATABASE_MODE=file # 改用文件数据库 export JUN_SERVER_MODE=server # 以 server 模式启动 export JUN_SERVER_PORT=8080 # 修改监听端口 ``` --- ## 目录结构说明 ``` junx-ddd-app/ ├── build/ # Wails 构建配置（各平台 Taskfile、plist、打包脚本） ├── configs/ │ └── config.yaml # 运行时配置（可用 JUN_ 环境变量覆盖） ├── design/ # 设计稿（HTML / CSS 原型） ├── docs/ # 文档 │ ├── git-branch-guide.md # Git 分支规范 │ └── plugin-development.md # 插件应用开发文档 ├── frontend/ # Vue 3 + TS + Vite 前端 SPA │ ├── src/ │ │ ├── api/ # 后端接口调用封装 │ │ ├── components/ # 通用组件 │ │ ├── config/ # 导航与静态配置 │ │ ├── router/ # 前端路由 │ │ ├── stores/ # Pinia 状态 │ │ ├── utils/ # 环境检测(env.ts)、http 封装(http.ts) │ │ └── views/ # 页面视图 │ ├── vite.config.ts │ └── package.json ├── internal/ # Go 后端（严格 DDD 分层） │ ├── app/ # 组装层：依赖注入、Wails 应用创建 │ ├── binding/ # Wails Binding（暴露给前端的 Go 方法） │ ├── config/ # 配置加载（Viper + JUN_ 环境变量） │ ├── database/ # SQLite 初始化、迁移、seed 导入 │ ├── domain/ # 领域实体（纯 Go，无 ORM 标签） │ ├── logger/ # Zap 日志封装 │ ├── plugin/ # 插件系统核心 + 内置插件 │ │ ├── builtin/ # 统一注册所有内置插件 │ │ ├── bbsysinfo/ # 系统信息插件（综合型：路由 + Wails 绑定） │ │ ├── bbcreatecmd/ # 命令应用批量创建插件（Wails 绑定型） │ │ └── bbcreateonline/ # 在线应用批量创建插件（Wails 绑定型） │ ├── registry/ # 内置应用注册 │ ├── repository/ # 仓库接口 + GORM 实现 │ ├── server/ # Gin 引擎、路由、配置/KV 路由 │ ├── service/ # 业务逻辑层 │ ├── wailsmgr/ # Wails 窗口/应用管理 │ ├── utils/ # ID 生成等工具 │ └── buildinfo/ # 编译期注入的版本信息 ├── scripts/ # SQL seed 脚本 ├── main.go # 程序入口 ├── go.mod / go.sum # Go 模块 ├── Taskfile.yml # 任务编排（dev/build/run/server…） └── package.json # 根级前端依赖声明 ``` 依赖方向（只向内）：`router/server → binding → service → repository → domain`，组装层 `internal/app` 负责把所有层连起来。 --- ## 插件系统简介 插件是平台的核心扩展机制。一个插件只需实现 `plugin.Plugin` 核心接口，并可按需叠加两种可选能力： | 能力接口 | 作用 | 典型场景 | | --- | --- | --- | | `Plugin`（核心） | 生命周期管理（Init / Shutdown） | 所有插件必备 | | `RoutablePlugin` | 注册 HTTP/REST 路由 | 提供后端 API（server / 浏览器模式） | | `WailsBindablePlugin` | 暴露 Wails Binding 给前端 | 桌面双通道调用 | 按能力组合，插件可分为**基础型、路由型、Wails 绑定型、综合型**四种，详细开发流程、规范与完整示例见 **[`docs/plugin-development.md`](docs/plugin-development.md)**。 --- ## 版本信息 | 项目 | 值 | | --- | --- | | 当前分支 | `release/v0.0.1` | | 应用版本（配置） | `0.1.0`（`configs/config.yaml`） | | Go 版本 | `1.25.0`（`go.mod`） | | 前端构建 | Vue 3 + Vite 8 | | 构建信息注入 | 通过 `ldflags` 注入 `internal/buildinfo` 的 `Version` / `Commit` / `BuildTime` | ```bash # 示例：带版本信息的构建 go build -ldflags "\ -X junx-ddd-app/internal/buildinfo.Version=0.1.0 \ -X junx-ddd-app/internal/buildinfo.Commit=$(git rev-parse --short HEAD) \ -X junx-ddd-app/internal/buildinfo.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" ``` 运行时版本可在日志首行（`应用启动` 事件）或 `buildinfo.Info()` 中查看。 --- ## 开源许可证声明 MIT-0