nuxt-gin-tools 0.2.0 → 0.2.2

package/README.md

@@ -1,23 +1,135 @@
 # nuxt-gin-tools
 
-This project is used as a dependency for [nuxt-gin-starter](https://github.com/RapboyGao/nuxt-gin-starter.git)
+`nuxt-gin-tools` 是 `nuxt-gin-starter` 的配套开发工具包，提供 Nuxt + Gin 项目的统一命令入口。
 
-## Command: nuxt-gin dev
+核心目标：
+- 一条命令启动前后端开发环境
+- 自动处理 Go 侧依赖和文件监听重启
+- 提供 OpenAPI 代码生成与构建打包辅助
 
-- Starting the develop server.
+## 功能概览
 
-## Command: nuxt-gin build
+- `nuxt-gin dev`
+  - 启动 Nuxt 开发服务
+  - 启动 Go 文件监听（基于 `chokidar`）
+  - Go 文件变化后自动重启 `go run main.go`
+- `nuxt-gin install`
+  - 执行 Nuxt prepare
+  - 如果检测到 Go，则执行 `go mod download && go mod tidy`
+- `nuxt-gin gen`
+  - 基于 `openapi.yaml` 生成 Go / TS API 代码
+- `nuxt-gin build`
+  - 执行项目构建与打包流程
+- `nuxt-gin cleanup`
+  - 清理开发产物
+- `nuxt-gin update`
+  - 执行依赖更新流程
 
-- Build script
+## 安装
 
-## Command: nuxt-gin gen
+在 `nuxt-gin-starter` 项目中作为依赖安装：
 
-- Generate API based on openapi.yaml
+```bash
+pnpm add nuxt-gin-tools
+```
 
-## Command: nuxt-gin install
+## 快速开始
 
-- Postinstall script.
+```bash
+# 初始化依赖（可选）
+nuxt-gin install
 
-## Command: nuxt-gin cleanup
+# 启动开发
+nuxt-gin dev
+```
+
+## 命令说明
+
+### `nuxt-gin dev`
+
+开发模式下会并行运行：
+- Nuxt：`npx nuxt dev --port=<nuxtPort> --host`
+- Go：监听变更并运行 `go run main.go`
+
+Go 监听规则来自 `.go-watch.json`（见下文）。
+
+### `nuxt-gin install`
+
+- 总是执行：`npx nuxt prepare`
+- 检测到 Go 时额外执行：`go mod download && go mod tidy`
+
+### `nuxt-gin gen`
+
+依赖 `openapi-generator-cli`，默认会：
+- 生成 Go Gin server 相关代码
+- 生成 TypeScript axios 客户端代码
+
+### `nuxt-gin build`
+
+执行工具链内置的构建与打包逻辑。
+
+### `nuxt-gin cleanup`
+
+清理由工具链生成的临时目录和产物。
+
+### `nuxt-gin update`
+
+执行项目约定的更新逻辑。
+
+## 配置
+
+### 1) `server.config.json`
+
+`dev` 命令会读取该文件，常用字段：
+
+- `ginPort`: Gin 服务端口
+- `nuxtPort`: Nuxt 开发端口
+- `baseUrl`: Nuxt baseUrl
+- `killPortBeforeDevelop`: 开发前是否释放端口（默认 `true`）
+- `cleanupBeforeDevelop`: 开发前是否执行 cleanup（默认 `false`）
+
+### 2) `.go-watch.json`
+
+Go 监听配置文件，示例：
+
+```json
+{
+  "tmpDir": ".build/.server",
+  "testDataDir": "testdata",
+  "includeExt": ["go", "tpl", "html"],
+  "includeDir": [],
+  "includeFile": [],
+  "excludeDir": [
+    "assets",
+    ".build/.server",
+    "vendor",
+    "testdata",
+    "node_modules",
+    "vue",
+    "api",
+    ".vscode",
+    ".git"
+  ],
+  "excludeFile": [],
+  "excludeRegex": ["_test.go"]
+}
+```
+
+也支持环境变量指定路径：
+
+```bash
+NUXT_GIN_WATCH_CONFIG=/path/to/.go-watch.json
+```
+
+## 环境依赖
+
+- Node.js
+- pnpm
+- Go（需要运行 Gin 侧开发与依赖下载时）
+- `openapi-generator-cli`（仅 `nuxt-gin gen` 需要）
+
+## 说明
+
+- Go 侧热更新已不再依赖 Air。
+- 当前方案为：`chokidar` 监听文件变化 + 重启 `go run main.go`。
 
-- Cleanup script.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-gin-tools",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "This project is used as a dependency for [nuxt-gin-starter](https://github.com/RapboyGao/nuxt-gin-starter.git)",
   "bin": {
     "nuxt-gin": "index.js"

package/src/dev-go.d.ts

@@ -1 +1,8 @@
-export {};
+/**
+ * 启动 Go 开发监听流程：执行 `go run main.go`，并在文件变更后自动重启。
+ *
+ * 该函数通常由 `develop()` 调用；执行后会持续监听，直到收到退出信号。
+ *
+ * @returns {Promise<void>} 仅在监听流程被中断并完成清理后返回。
+ */
+export declare function startGoDev(): Promise<void>;

package/src/dev-go.js

@@ -12,6 +12,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.startGoDev = startGoDev;
 const child_process_1 = require("child_process");
 const child_process_2 = require("child_process");
 const chokidar_1 = __importDefault(require("chokidar"));
@@ -306,7 +307,14 @@ function stopGoProcess(proc) {
         });
     });
 }
-function start() {
+/**
+ * 启动 Go 开发监听流程：执行 `go run main.go`，并在文件变更后自动重启。
+ *
+ * 该函数通常由 `develop()` 调用；执行后会持续监听，直到收到退出信号。
+ *
+ * @returns {Promise<void>} 仅在监听流程被中断并完成清理后返回。
+ */
+function startGoDev() {
     return __awaiter(this, void 0, void 0, function* () {
         const watchConfig = loadWatchConfig();
         const watchRoots = watchConfig.includeDir.length
@@ -368,7 +376,10 @@ function start() {
         }));
     });
 }
-start().catch((error) => {
-    console.error(chalk_1.default.red(`[${LOG_TAG}] failed to start: ${String(error)}`));
-    process.exit(1);
-});
+if (require.main === module) {
+    // 兼容直接执行该文件（例如 node src/dev-go.js）。
+    startGoDev().catch((error) => {
+        console.error(chalk_1.default.red(`[${LOG_TAG}] failed to start: ${String(error)}`));
+        process.exit(1);
+    });
+}

package/src/develop.d.ts

@@ -1,2 +1,9 @@
+/**
+ * 启动本地开发环境。
+ *
+ * 行为包括：按配置执行预清理、释放开发端口、并行启动 Nuxt 与 Go 监听流程。
+ *
+ * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
+ */
 export declare function develop(): Promise<void>;
 export default develop;

package/src/develop.js

@@ -21,12 +21,9 @@ const child_process_1 = require("child_process");
 const chalk_1 = __importDefault(require("chalk"));
 const cleanup_1 = __importDefault(require("./cleanup"));
 const postinstall_1 = __importDefault(require("./postinstall"));
+const dev_go_1 = require("./dev-go");
 const cwd = process.cwd();
 const serverConfig = (0, fs_extra_1.readJSONSync)((0, path_1.join)(cwd, "server.config.json"));
-function getGoDevCommand() {
-    const scriptPath = (0, path_1.join)(__dirname, "dev-go.js");
-    return `"${process.execPath}" "${scriptPath}"`;
-}
 function killPort(port) {
     if (!Number.isInteger(port)) {
         return;
@@ -121,6 +118,13 @@ function killPortsFromConfig() {
         }
     }
 }
+/**
+ * 启动本地开发环境。
+ *
+ * 行为包括：按配置执行预清理、释放开发端口、并行启动 Nuxt 与 Go 监听流程。
+ *
+ * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
+ */
 function develop() {
     return __awaiter(this, void 0, void 0, function* () {
         const cleanupBeforeDevelop = serverConfig.cleanupBeforeDevelop === true;
@@ -142,18 +146,16 @@ function develop() {
             killPortsFromConfig();
         }
         (0, fs_extra_1.ensureDirSync)((0, path_1.join)(cwd, ".build/.server"));
-        yield (0, concurrently_1.default)([
-            {
-                command: getGoDevCommand(),
-                name: "go",
-                prefixColor: "green",
-            },
+        // Nuxt 保持在 concurrently 中运行，统一复用 nuxt 标签输出。
+        const nuxtTask = (0, concurrently_1.default)([
             {
                 command: `npx nuxt dev --port=${serverConfig.nuxtPort} --host`,
                 name: "nuxt",
                 prefixColor: "blue",
             },
         ]).result;
+        // Go 侧直接调用本地 dev-go 逻辑，避免额外 shell 路径和引号问题。
+        yield Promise.all([(0, dev_go_1.startGoDev)(), nuxtTask]);
     });
 }
 exports.default = develop;