From a77e16a150a5af8ecf8eee3c9a6d290bb4d872ce Mon Sep 17 00:00:00 2001 From: zerosaturation Date: Mon, 13 Apr 2026 12:02:12 +0800 Subject: [PATCH] docs: translate hot-reload dev script spec to Chinese Co-Authored-By: Claude Opus 4.6 --- ...2026-04-13-hot-reload-dev-script-design.md | 106 +++++++++--------- 1 file changed, 53 insertions(+), 53 deletions(-) diff --git a/docs/superpowers/specs/2026-04-13-hot-reload-dev-script-design.md b/docs/superpowers/specs/2026-04-13-hot-reload-dev-script-design.md index b0fa9c9..05e7448 100644 --- a/docs/superpowers/specs/2026-04-13-hot-reload-dev-script-design.md +++ b/docs/superpowers/specs/2026-04-13-hot-reload-dev-script-design.md @@ -1,80 +1,80 @@ -# Hot-Reload Dev Script Design (dev.sh) +# 热更新开发脚本设计 (dev.sh) -## 1. Overview +## 1. 概述 -`dev.sh` is a development script that starts all backend microservices with file-watching hot-reload. When any `.go` file changes in a service's directory, only that specific service is recompiled and restarted. +`dev.sh` 是一个开发脚本，用于启动所有后端微服务并监听文件变化，实现热更新。当某个服务的 `.go` 文件发生变更时，只重新编译和重启该服务。 -## 2. Architecture +## 2. 架构 ``` dev.sh -├── Load .env (same as start.sh) -├── Start all services in dependency order (background) -└── Run multiple concurrent file watchers (background) - ├── watcher(gateway) → monitors gateway/ → restart gateway - ├── watcher(userService) → monitors services/userService/ → restart userService - ├── watcher(assetService) → monitors services/assetService/ → restart assetService - ├── watcher(socialService) → monitors services/socialService/ → restart socialService - ├── watcher(galleryService) → monitors services/galleryService/ → restart galleryService - └── watcher(activityService) → monitors services/activityService/ → restart activityService +├── 加载 .env 文件（与 start.sh 相同） +├── 按依赖顺序启动所有服务（后台运行） +└── 并发运行多个文件监听器（后台运行） + ├── watcher(gateway) → 监听 gateway/ → 重启 gateway + ├── watcher(userService) → 监听 services/userService/ → 重启 userService + ├── watcher(assetService) → 监听 services/assetService/ → 重启 assetService + ├── watcher(socialService) → 监听 services/socialService/ → 重启 socialService + ├── watcher(galleryService) → 监听 services/galleryService/ → 重启 galleryService + └── watcher(activityService) → 监听 services/activityService/ → 重启 activityService ``` -## 3. Service Startup Order +## 3. 服务启动顺序 -Same as `start.sh`: -1. userService (port 20000) -2. assetService (port 20003) -3. socialService (port 20002) -4. galleryService (port 20004) -5. activityService (port 20005) -6. gateway (port 8080) +与 `start.sh` 保持一致： +1. userService (端口 20000) +2. assetService (端口 20003) +3. socialService (端口 20002) +4. galleryService (端口 20004) +5. activityService (端口 20005) +6. gateway (端口 8080) -## 4. Watcher Behavior +## 4. 监听器行为 -For each service: -- **Monitor**: `/**/*.go` -- **Trigger**: Any `.go` file create/modify/write event -- **Debounce**: 300ms cooldown — after a restart is triggered, ignore further events for 300ms to avoid rapid successive rebuilds. -- **Action** (executed inside service's own module directory, matching `start.sh`): - 1. Recompile: `cd && go build -o .` - 2. **Build-failure safety**: If build fails, log the error and keep the old process running - 3. Only after successful build: kill the running service process - 4. Restart with same arguments as `start.sh` - 5. Log the event to console (cyan color) +每个服务对应一个独立的监听器： +- **监听范围**: `/**/*.go` +- **触发条件**: 任意 `.go` 文件的创建/修改/写入事件 +- **防抖**: 300ms 冷却期 —— 触发重启后，300ms 内的后续事件会被忽略，避免频繁重建 +- **操作步骤**（在服务自己的模块目录下执行，与 `start.sh` 一致）: + 1. 重新编译: `cd && go build -o .` + 2. **构建失败安全**: 若编译失败，记录错误日志，保持旧进程继续运行 + 3. 仅在编译成功后: 终止旧进程 + 4. 使用与 `start.sh` 相同的参数启动新进程 + 5. 在控制台输出热更新事件（青色） -## 5. Dependencies +## 5. 依赖工具 -- **Mac**: `fswatch` (install via `brew install fswatch`) -- **Linux**: `inotifywait` (install via package manager) +- **Mac**: `fswatch`（通过 `brew install fswatch` 安装） +- **Linux**: `inotifywait`（通过系统包管理器安装） -If the required tool is not installed, the script prints a clear installation instruction and exits. +若所需工具未安装，脚本打印安装说明后退出。 -## 6. Signal Handling +## 6. 信号处理 -- `Ctrl+C` / SIGINT / SIGTERM: Use a `trap` to catch signals — stop all services and watchers, then exit -- On exit: Kill all service processes and watcher processes in reverse startup order (gateway first, then services) +- **Ctrl+C / SIGINT / SIGTERM**: 使用 `trap` 捕获信号，停止所有服务和监听器后退出 +- 退出时按启动相反顺序（先 gateway，再各个服务）杀灭所有进程 -## 7. Logging +## 7. 日志 -- Each service logs to `/tmp/.log` (same as start.sh) -- Console output shows which file changed and which service was restarted -- Hot-reload events are printed in distinct color (cyan) +- 各服务日志写入 `/tmp/.log`（与 start.sh 相同） +- 控制台显示变更的文件路径和被重启的服务 +- 热更新事件以青色输出 -## 8. File Structure +## 8. 文件结构 ``` backend/ -├── dev.sh # Main dev script (new) -└── start.sh # Production start script (existing) +├── dev.sh # 热更新开发脚本（新增） +└── start.sh # 生产环境启动脚本（现有） ``` -## 9. Edge Cases +## 9. 边界情况 -- **Build failure**: Old process keeps running; error is logged to console and `/tmp/.log` -- **Watched directory missing**: Script exits with error if monitored directory does not exist -- **Tool not found**: Script prints installation instructions and exits -- **Rapid file changes**: 300ms debounce prevents immediate successive rebuilds; each batch of changes triggers at most one restart +- **构建失败**: 旧进程保持运行，错误同时记录到控制台和 `/tmp/.log` +- **监听目录不存在**: 脚本退出并报错 +- **工具未安装**: 打印安装说明后退出 +- **文件快速连续变更**: 300ms 防抖机制确保每批变更最多触发一次重启 -## 10. No Changes to Existing Files +## 10. 不修改现有文件 -`dev.sh` does not modify any existing files. It only reads `start.sh` for reference and adds a new file. +`dev.sh` 不修改任何现有文件，仅参考 `start.sh` 的实现逻辑，并新增一个文件。