Initial project setup with Go backend, React frontend, and Neutralino desktop shell
This commit is contained in:
256
README.md
Normal file
256
README.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# Nex
|
||||
|
||||
基于 [NeutralinoJS](https://neutralino.js.org) 的轻量级桌面应用框架，前端使用 React + TypeScript + Vite，后端使用 Go 作为 Native Extension。
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
nex/
|
||||
├── neutralino.config.json # Neutralino 主配置文件
|
||||
├── README.md
|
||||
├── bin/ # Neutralino 运行时二进制文件（各平台）
|
||||
│ ├── neutralino-win_x64.exe
|
||||
│ ├── neutralino-linux_x64
|
||||
│ ├── neutralino-linux_arm64
|
||||
│ ├── neutralino-linux_armhf
|
||||
│ ├── neutralino-mac_x64
|
||||
│ ├── neutralino-mac_arm64
|
||||
│ └── neutralino-mac_universal
|
||||
├── frontend/ # 前端项目（React + TypeScript + Vite）
|
||||
│ ├── package.json
|
||||
│ ├── index.html # Vite 入口 HTML
|
||||
│ ├── vite.config.ts
|
||||
│ ├── tsconfig.json
|
||||
│ ├── biome.json # Biome 格式化配置
|
||||
│ ├── eslint.config.js # ESLint 配置
|
||||
│ ├── public/ # 静态资源
|
||||
│ │ └── favicon.svg
|
||||
│ ├── dist/ # 构建产物（由 vite build 生成）
|
||||
│ └── src/
|
||||
│ ├── main.tsx # 应用入口，初始化 React 和 Neutralino
|
||||
│ ├── App.tsx # 根组件
|
||||
│ ├── components/ # 可复用 UI 组件
|
||||
│ ├── pages/ # 页面组件
|
||||
│ ├── hooks/ # 自定义 React Hooks
|
||||
│ ├── utils/ # 工具函数
|
||||
│ ├── types/ # TypeScript 类型定义
|
||||
│ └── styles/
|
||||
│ └── global.scss # 全局样式
|
||||
└── backend/ # 后端项目（Go Native Extension）
|
||||
├── go.mod / go.sum # Go 模块依赖
|
||||
├── build.sh # macOS / Linux 构建脚本
|
||||
├── build.cmd # Windows 构建脚本
|
||||
├── cmd/
|
||||
│ └── nex/
|
||||
│ └── main.go # Go 扩展入口，定义事件处理与业务逻辑
|
||||
└── internal/
|
||||
└── neutralino/
|
||||
└── client.go # Neutralino WebSocket 客户端通信库
|
||||
```
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 层级 | 技术 |
|
||||
|------|------|
|
||||
| 桌面框架 | NeutralinoJS 6.7.0 |
|
||||
| 前端 | React 19 + TypeScript 6 |
|
||||
| 构建工具 | Vite 8 + Bun |
|
||||
| 样式 | SCSS |
|
||||
| 代码检查 | ESLint + Biome |
|
||||
| 后端 | Go 1.22 |
|
||||
| 后端通信 | WebSocket (gorilla/websocket) |
|
||||
|
||||
## 架构说明
|
||||
|
||||
本项目采用 Neutralino Extension 架构，前后端通过 WebSocket 进行异步通信：
|
||||
|
||||
```
|
||||
┌─────────────────┐ WebSocket ┌──────────────┐
|
||||
│ React Frontend │ ◄────────────► │ Go Backend │
|
||||
│ (浏览器渲染) │ │ (Extension) │
|
||||
└─────────────────┘ └──────────────┘
|
||||
│ │
|
||||
@neutralinojs/lib internal/neutralino
|
||||
(JS API 调用) (WSClient)
|
||||
```
|
||||
|
||||
- **前端** 通过 `@neutralinojs/lib` 的 `init()` 初始化 Neutralino 运行时，使用 `Neutralino.events` 发送和监听事件。
|
||||
- **后端** 作为 Neutralino Extension 启动，通过 WebSocket 与 Neutralino 核心通信，接收前端事件并响应。
|
||||
- 所有事件通信均为异步，事件队列保证不丢失。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 环境要求
|
||||
|
||||
- [Go](https://go.dev/dl/) >= 1.22
|
||||
- [Bun](https://bun.sh/)（推荐）或 Node.js >= 18
|
||||
- [Neutralino CLI](https://neutralino.js.org/docs/cli/neu-cli/)：`npm install -g @neutralinojs/neu`
|
||||
|
||||
### 1. 安装前端依赖
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
bun install
|
||||
```
|
||||
|
||||
### 2. 编译 Go 后端
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# macOS / Linux
|
||||
./build.sh
|
||||
|
||||
# Windows
|
||||
build.cmd
|
||||
```
|
||||
|
||||
构建产物 `nex`（或 `nex.exe`）输出到 `backend/` 目录下。
|
||||
|
||||
### 3. 安装 Neutralino 二进制
|
||||
|
||||
```bash
|
||||
neu update
|
||||
```
|
||||
|
||||
### 4. 开发模式运行
|
||||
|
||||
```bash
|
||||
neu run
|
||||
```
|
||||
|
||||
此命令会启动 Vite 开发服务器（端口 5173）和 Neutralino 窗口，前端改动自动热更新。
|
||||
|
||||
### 5. 构建生产包
|
||||
|
||||
```bash
|
||||
# 构建前端
|
||||
cd frontend && bun run build
|
||||
|
||||
# 构建 Neutralino 应用
|
||||
neu build
|
||||
```
|
||||
|
||||
## 前端开发指引
|
||||
|
||||
### 路径别名
|
||||
|
||||
项目配置了 `@` 指向 `src/` 目录，在导入时可直接使用：
|
||||
|
||||
```ts
|
||||
import App from "@/App.tsx";
|
||||
import "@/styles/global.scss";
|
||||
```
|
||||
|
||||
### 目录规范
|
||||
|
||||
| 目录 | 用途 |
|
||||
|------|------|
|
||||
| `src/components/` | 可复用 UI 组件，通过 `index.ts` 统一导出 |
|
||||
| `src/pages/` | 页面级组件 |
|
||||
| `src/hooks/` | 自定义 React Hooks |
|
||||
| `src/utils/` | 工具函数 |
|
||||
| `src/types/` | TypeScript 类型定义 |
|
||||
| `src/styles/` | 全局及局部样式（SCSS） |
|
||||
|
||||
### 代码质量工具
|
||||
|
||||
```bash
|
||||
# ESLint 检查
|
||||
bun run lint
|
||||
|
||||
# ESLint 自动修复
|
||||
bun run lint:fix
|
||||
|
||||
# Biome 格式化检查
|
||||
bun run format:check
|
||||
|
||||
# Biome 格式化（写入）
|
||||
bun run format
|
||||
|
||||
# TypeScript 类型检查
|
||||
bun run typecheck
|
||||
```
|
||||
|
||||
### 调用 Go 后端
|
||||
|
||||
前端通过 Neutralino 事件系统与 Go 后端通信：
|
||||
|
||||
```ts
|
||||
// 发送事件到 Go 后端
|
||||
Neutralino.events.dispatch("runGo", {
|
||||
function: "ping",
|
||||
parameter: "Hello from Frontend",
|
||||
});
|
||||
|
||||
// 监听 Go 后端返回的事件
|
||||
Neutralino.events.on("pingResult", (event) => {
|
||||
console.log(event.detail);
|
||||
});
|
||||
```
|
||||
|
||||
## 后端开发指引
|
||||
|
||||
### 目录结构
|
||||
|
||||
```
|
||||
backend/
|
||||
├── cmd/nex/main.go # 入口，注册事件回调
|
||||
├── internal/neutralino/client.go # WSClient 通信库
|
||||
├── build.sh / build.cmd # 构建脚本
|
||||
└── go.mod / go.sum # 依赖管理
|
||||
```
|
||||
|
||||
### 添加新的 Go 函数
|
||||
|
||||
在 `cmd/nex/main.go` 的 `processAppEvent` 回调中添加新的函数分支：
|
||||
|
||||
```go
|
||||
func processAppEvent(data neutralino.EventMessage) {
|
||||
if ext.IsEvent(data, "runGo") {
|
||||
if d, ok := data.Data.(map[string]interface{}); ok {
|
||||
if d["function"] == "myFunc" {
|
||||
result := make(map[string]interface{})
|
||||
result["result"] = "处理结果"
|
||||
ext.Send("myFuncResult", result)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### WSClient API
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| `Run(callback, debug)` | 启动扩展主循环，每条消息触发 callback |
|
||||
| `IsEvent(data, eventName)` | 判断事件名是否匹配 |
|
||||
| `Send(event, data)` | 向前端发送结构化事件（`map[string]interface{}`） |
|
||||
| `SendMessageString(event, data)` | 向前端发送字符串事件 |
|
||||
|
||||
修改后端代码后需重新编译：
|
||||
|
||||
```bash
|
||||
cd backend && ./build.sh # 或 build.cmd
|
||||
```
|
||||
|
||||
## Neutralino 配置说明
|
||||
|
||||
`neutralino.config.json` 关键配置：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `applicationId` | 应用标识 `com.lanyuanxiaoyao.nex` |
|
||||
| `defaultMode` | 默认以窗口模式运行 |
|
||||
| `documentRoot` | 前端资源根路径 `/frontend/` |
|
||||
| `cli.resourcesPath` | 构建时打包的前端产物路径 `/frontend/dist` |
|
||||
| `cli.extensionsPath` | 后端扩展路径 `/backend/` |
|
||||
| `extensions` | 扩展定义，指定各平台启动命令 |
|
||||
| `nativeAllowList` | Native API 白名单 |
|
||||
|
||||
## 参考链接
|
||||
|
||||
- [NeutralinoJS 官方文档](https://neutralino.js.org/docs/)
|
||||
- [React 官方文档](https://react.dev/)
|
||||
- [Vite 官方文档](https://vite.dev/)
|
||||
- [Go 官方文档](https://go.dev/doc/)
|
||||
Reference in New Issue
Block a user