feat(app): 实现优雅停机功能

- 新增 shuttingDown 原子布尔标志和 shutdownOnce 保证单次执行
- 添加 DrainTimeout 和 ShutdownTimeout 配置参数，默认 5s 和 30s
- 修改 ServeHTTP 拦截新请求返回 503 Service Unavailable
- 实现跨平台信号处理：Windows 关窗口和 Linux SIGTERM/SIGINT
- 添加 recover 保护避免停机过程中 panic 触发重启
- 优化 HTTP 服务退出判断，排除正常关闭情况
- 新增 log.LoggerNoCaller 用于访问日志等无意义调用方场景
- 更新 README 文档增加优雅停机特性说明和文档链接
- 创建详细的优雅停机文档和测试用例
- 添加 Windows 平台特定信号处理实现
- 新增 .cursor 计划文件记录开发方案

application.go

@@ -1,14 +1,19 @@
 package hotime
 
 import (
+	"context"
 	"database/sql"
 	"io/ioutil"
 	"net/http"
 	"net/url"
 	"os"
+	"os/signal"
 	"path/filepath"
 	"strconv"
 	"strings"
+	"sync"
+	"sync/atomic"
+	"syscall"
 	"time"
 
 	. "code.hoteas.com/golang/hotime/cache"
@@ -34,12 +39,41 @@ type Application struct {
 	*HoTimeCache
 	*http.Server
 	http.Handler
+	shuttingDown    atomic.Bool   // 停机标志，置为 true 后新请求立即返回 503
+	shutdownOnce    sync.Once     // 保证多路触发（信号/关窗口）只执行一次
+	DrainTimeout    time.Duration // 返回 503 后等 nginx 切流的时长，默认 5s
+	ShutdownTimeout time.Duration // 等在途请求完成的最长时间，默认 30s
 }
 
 func (that *Application) ServeHTTP(w http.ResponseWriter, req *http.Request) {
+	if that.shuttingDown.Load() {
+		w.Header().Set("Connection", "close")
+		http.Error(w, "Service Unavailable", http.StatusServiceUnavailable)
+		return
+	}
 	that.handler(w, req)
 }
 
+// initiateGracefulShutdown 触发优雅停机，通过 sync.Once 保证多路触发只执行一次。
+// drain: 返回 503 后等待上游（nginx）完成流量切换的时长。
+// shutdown: 等待在途请求完成的最长时间。
+func (that *Application) initiateGracefulShutdown(drain, shutdown time.Duration) {
+	that.shutdownOnce.Do(func() {
+		that.shuttingDown.Store(true)
+		that.Log.Infof("优雅停机：新请求已返回 503，等 %v 让 nginx 完成流量切换...", drain)
+		time.Sleep(drain)
+		ctx, cancel := context.WithTimeout(context.Background(), shutdown)
+		defer cancel()
+		that.Log.Infof("停止接受新连接，等进行中请求完成（最多 %v）...", shutdown)
+		if err := that.Server.Shutdown(ctx); err != nil {
+			that.Log.Errorf("优雅停机超时，强制关闭: %v", err)
+		} else {
+			that.Log.Infof("服务已安全关闭")
+		}
+		os.Exit(0)
+	})
+}
+
 // Run 启动实例
 func (that *Application) Run(router Router) {
 	//如果没有设置配置自动生成配置
@@ -125,6 +159,9 @@ func (that *Application) Run(router Router) {
 	//异常处理
 	defer func() {
 		if err := recover(); err != nil {
+			if that.shuttingDown.Load() {
+				return // 停机过程中的 panic 不触发重启
+			}
 			//that.SetError(errors.New(fmt.Sprint(err)), LOG_FMT)
 			that.Log.Warnf("%v", err)
 
@@ -146,8 +183,10 @@ func (that *Application) Run(router Router) {
 			//启动服务
 			that.Server.Addr = ":" + that.Port
 			err := that.Server.ListenAndServe()
-			that.Log.Error().Err(err).Msg("HTTP 服务退出")
-			ch <- 1
+			if err != nil && err != http.ErrServerClosed {
+				that.Log.Error().Err(err).Msg("HTTP 服务退出")
+				ch <- 1
+			}
 
 		}()
 	}
@@ -160,8 +199,10 @@ func (that *Application) Run(router Router) {
 			//启动服务
 			that.Server.Addr = ":" + that.TLSPort
 			err := that.Server.ListenAndServeTLS(that.Config.GetString("tlsCert"), that.Config.GetString("tlsKey"))
-			that.Log.Error().Err(err).Msg("HTTPS 服务退出")
-			ch <- 2
+			if err != nil && err != http.ErrServerClosed {
+				that.Log.Error().Err(err).Msg("HTTPS 服务退出")
+				ch <- 2
+			}
 
 		}()
 	}
@@ -171,6 +212,25 @@ func (that *Application) Run(router Router) {
 
 	}
 
+	// 注册 Windows 关窗口处理（Linux/macOS 上是空实现）
+	that.registerWindowsCloseHandler()
+
+	// 跨平台信号监听：Ctrl+C / SIGTERM（kill 命令）/ taskkill /PID
+	go func() {
+		sigCh := make(chan os.Signal, 1)
+		signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)
+		<-sigCh
+		drain := that.DrainTimeout
+		if drain == 0 {
+			drain = 5 * time.Second
+		}
+		shutdown := that.ShutdownTimeout
+		if shutdown == 0 {
+			shutdown = 30 * time.Second
+		}
+		that.initiateGracefulShutdown(drain, shutdown)
+	}()
+
 	value := <-ch
 
 	that.Log.Errorf("启动服务失败 : %s", ObjToStr(value))
@@ -256,7 +316,7 @@ func (that *Application) SetConfig(configPath ...string) {
 	that.Log = log.NewLogger(logLevel, logFile, logHistory)
 	that.Db.Log = that.Log
 	if that.Config.Get("webConnectLogShow") == nil || that.Config.GetBool("webConnectLogShow") {
-		that.WebConnectLog = log.NewLogger(1, that.Config.GetString("webConnectLogFile"), 0)
+		that.WebConnectLog = log.NewLoggerNoCaller(1, that.Config.GetString("webConnectLogFile"), 0)
 	}
 
 }