zerosaturation 127139439f docs: add hot-reload dev script design spec

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-04-13 12:00:46 +08:00

3.3 KiB

Raw Blame History

Hot-Reload Dev Script Design (dev.sh)

1. Overview

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.

2. Architecture

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

3. Service Startup Order

Same as start.sh:

userService (port 20000)
assetService (port 20003)
socialService (port 20002)
galleryService (port 20004)
activityService (port 20005)
gateway (port 8080)

4. Watcher Behavior

For each service:

Monitor: <service_dir>/**/*.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 <service_dir> && go build -o <binary> .
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)

5. Dependencies

Mac: fswatch (install via brew install fswatch)
Linux: inotifywait (install via package manager)

If the required tool is not installed, the script prints a clear installation instruction and exits.

6. Signal Handling

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)

7. Logging

Each service logs to /tmp/<service_name>.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)

8. File Structure

backend/
├── dev.sh          # Main dev script (new)
└── start.sh        # Production start script (existing)

9. Edge Cases

Build failure: Old process keeps running; error is logged to console and /tmp/<service>.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

10. No Changes to Existing Files

dev.sh does not modify any existing files. It only reads start.sh for reference and adds a new file.

3.3 KiB Raw Blame History