251 lines
7.3 KiB
Go
251 lines
7.3 KiB
Go
package bootstrap
|
||
|
||
import (
|
||
"context"
|
||
"errors"
|
||
"fmt"
|
||
"net/http"
|
||
"os"
|
||
"os/signal"
|
||
"sync"
|
||
"syscall"
|
||
"time"
|
||
|
||
"cloudnest/internal/config"
|
||
"cloudnest/internal/pkg/logger"
|
||
"github.com/gin-gonic/gin"
|
||
)
|
||
|
||
// Server encapsulates HTTP server lifecycle management with graceful start/restart/shutdown.
|
||
// Server 封装了 HTTP 服务器的生命周期管理，支持优雅启动/重启/关闭。
|
||
//
|
||
// Features:
|
||
// 1. Graceful startup with port auto-detection in dev mode
|
||
// 2. Graceful shutdown on SIGINT/SIGTERM signals
|
||
// 3. Hot reload on SIGHUP signal (Linux/Mac only) - re-reads config
|
||
// 4. Waits for in-flight requests to complete before shutdown
|
||
//
|
||
// 特性：
|
||
// 1. 开发模式下优雅启动，自动检测可用端口
|
||
// 2. 收到 SIGINT/SIGTERM 信号时优雅关闭
|
||
// 3. 收到 SIGHUP 信号时热重载（仅 Linux/Mac），重新读取配置
|
||
// 4. 关闭前等待正在进行的请求完成
|
||
type Server struct {
|
||
cfg *config.Config
|
||
engine *gin.Engine
|
||
srv *http.Server
|
||
mu sync.RWMutex
|
||
reloadChan chan os.Signal
|
||
shutdownOnce sync.Once
|
||
}
|
||
|
||
// NewServer creates a new Server instance with the given config and engine.
|
||
// NewServer 使用给定的配置和引擎创建新的 Server 实例。
|
||
//
|
||
// Parameters:
|
||
// - cfg: The application configuration.
|
||
// - engine: The Gin engine to serve.
|
||
//
|
||
// Returns:
|
||
// - *Server: A new Server instance.
|
||
//
|
||
// 参数:
|
||
// - cfg: 应用程序配置。
|
||
// - engine: 要服务的 Gin 引擎。
|
||
//
|
||
// 返回值:
|
||
// - *Server: 新的 Server 实例。
|
||
func NewServer(cfg *config.Config, engine *gin.Engine) *Server {
|
||
return &Server{
|
||
cfg: cfg,
|
||
engine: engine,
|
||
reloadChan: make(chan os.Signal, 1),
|
||
}
|
||
}
|
||
|
||
// Run starts the server and blocks until a shutdown signal is received.
|
||
// Run 启动服务器并阻塞，直到收到关闭信号。
|
||
//
|
||
// Lifecycle:
|
||
// 1. Auto-detect available port (dev mode only)
|
||
// 2. Start listening in a goroutine
|
||
// 3. Register signal handlers (SIGINT, SIGTERM for shutdown; SIGHUP for reload on Unix)
|
||
// 4. Block until shutdown signal
|
||
// 5. Gracefully shut down with timeout
|
||
//
|
||
// 生命周期：
|
||
// 1. 自动检测可用端口（仅开发模式）
|
||
// 2. 在 goroutine 中开始监听
|
||
// 3. 注册信号处理器（SIGINT、SIGTERM 用于关闭；SIGHUP 用于 Unix 上的重载）
|
||
// 4. 阻塞直到收到关闭信号
|
||
// 5. 使用超时优雅关闭
|
||
//
|
||
// Returns:
|
||
// - error: An error if startup or shutdown fails.
|
||
//
|
||
// 返回值:
|
||
// - error: 如果启动或关闭失败则返回错误。
|
||
func (s *Server) Run() error {
|
||
port := s.resolvePort()
|
||
addr := fmt.Sprintf("%s:%d", s.cfg.Server.Host, port)
|
||
|
||
s.mu.Lock()
|
||
s.srv = &http.Server{
|
||
Addr: addr,
|
||
Handler: s.engine,
|
||
}
|
||
s.mu.Unlock()
|
||
|
||
// Register signal handlers / 注册信号处理器
|
||
sigChan := make(chan os.Signal, 1)
|
||
signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
|
||
|
||
// Register SIGHUP for hot reload (Unix only)
|
||
// 注册 SIGHUP 用于热重载（仅 Unix）
|
||
if isUnix() {
|
||
signal.Notify(s.reloadChan, syscall.SIGHUP)
|
||
}
|
||
|
||
// Start server in a goroutine / 在 goroutine 中启动服务器
|
||
serverErr := make(chan error, 1)
|
||
go func() {
|
||
logger.Info("server listening", "address", addr, "env", s.cfg.App.Env)
|
||
if err := s.srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
|
||
serverErr <- err
|
||
}
|
||
close(serverErr)
|
||
}()
|
||
|
||
// Wait for signal / 等待信号
|
||
select {
|
||
case sig := <-sigChan:
|
||
logger.Info("shutdown signal received", "signal", sig.String())
|
||
return s.Shutdown()
|
||
case sig := <-s.reloadChan:
|
||
logger.Info("reload signal received, restarting", "signal", sig.String())
|
||
if err := s.Shutdown(); err != nil {
|
||
return err
|
||
}
|
||
// After shutdown, the caller should restart the process
|
||
// 关闭后，调用方应重启进程
|
||
return ErrReloadRequested
|
||
case err := <-serverErr:
|
||
if err != nil {
|
||
logger.Error("server failed", "error", err)
|
||
return err
|
||
}
|
||
return nil
|
||
}
|
||
}
|
||
|
||
// Shutdown gracefully shuts down the server with a timeout.
|
||
// Shutdown 使用超时优雅关闭服务器。
|
||
//
|
||
// Parameters:
|
||
// - timeout: The maximum time to wait for in-flight requests to complete.
|
||
//
|
||
// Returns:
|
||
// - error: An error if shutdown fails.
|
||
//
|
||
// Note:
|
||
// - Safe to call multiple times (subsequent calls are no-ops).
|
||
//
|
||
// 参数:
|
||
// - timeout: 等待正在进行的请求完成的最长时间。
|
||
//
|
||
// 返回值:
|
||
// - error: 如果关闭失败则返回错误。
|
||
//
|
||
// 注意:
|
||
// - 可以安全地多次调用（后续调用是空操作）。
|
||
func (s *Server) Shutdown() error {
|
||
var shutdownErr error
|
||
s.shutdownOnce.Do(func() {
|
||
s.mu.RLock()
|
||
srv := s.srv
|
||
s.mu.RUnlock()
|
||
|
||
if srv == nil {
|
||
return
|
||
}
|
||
|
||
timeout := time.Duration(s.cfg.Server.GracefulShutdownTimeout) * time.Second
|
||
ctx, cancel := context.WithTimeout(context.Background(), timeout)
|
||
defer cancel()
|
||
|
||
logger.Info("graceful shutdown started", "timeout_seconds", timeout)
|
||
if err := srv.Shutdown(ctx); err != nil {
|
||
logger.Error("graceful shutdown failed, forcing close", "error", err)
|
||
if closeErr := srv.Close(); closeErr != nil {
|
||
shutdownErr = fmt.Errorf("forced close failed: %w (original: %v)", closeErr, err)
|
||
return
|
||
}
|
||
shutdownErr = err
|
||
}
|
||
logger.Info("server exited gracefully")
|
||
})
|
||
return shutdownErr
|
||
}
|
||
|
||
// resolvePort finds an available port starting from the configured port.
|
||
// resolvePort 从配置的端口开始查找可用端口。
|
||
//
|
||
// In dev mode: tries configured port, then port+1, port+2, ..., up to +9.
|
||
// In prod mode: uses the configured port directly (no auto-switch).
|
||
//
|
||
// 开发模式：尝试配置端口，然后 port+1, port+2, ..., 最多 +9。
|
||
// 生产模式：直接使用配置的端口（不自动切换）。
|
||
//
|
||
// Returns:
|
||
// - int: The actual port to use.
|
||
//
|
||
// 返回值:
|
||
// - int: 实际使用的端口。
|
||
func (s *Server) resolvePort() int {
|
||
port := s.cfg.Server.Port
|
||
if !s.cfg.IsDev() {
|
||
return port
|
||
}
|
||
|
||
availablePort, err := config.FindAvailablePort(port, 10)
|
||
if err != nil {
|
||
logger.Fatal("no available port found", "preferred", port, "error", err)
|
||
}
|
||
if availablePort != port {
|
||
logger.Info("port auto-switched", "from", port, "to", availablePort)
|
||
}
|
||
return availablePort
|
||
}
|
||
|
||
// Addr returns the actual server address (host:port) after resolvePort has been called.
|
||
// Addr 返回调用 resolvePort 后的实际服务器地址（host:port）。
|
||
//
|
||
// Returns:
|
||
// - string: The server address, or empty string if server hasn't started.
|
||
//
|
||
// 返回值:
|
||
// - string: 服务器地址，如果服务器尚未启动则返回空字符串。
|
||
func (s *Server) Addr() string {
|
||
s.mu.RLock()
|
||
defer s.mu.RUnlock()
|
||
if s.srv == nil {
|
||
return ""
|
||
}
|
||
return s.srv.Addr
|
||
}
|
||
|
||
// isUnix returns true if the current OS is Unix-like (Linux, macOS, BSD, etc.).
|
||
// isUnix 如果当前操作系统是类 Unix 系统（Linux、macOS、BSD 等）则返回 true。
|
||
func isUnix() bool {
|
||
return os.PathSeparator == '/'
|
||
}
|
||
|
||
// ErrReloadRequested is returned by Run() when a SIGHUP signal requests a reload.
|
||
// ErrReloadRequested 当 SIGHUP 信号请求重载时由 Run() 返回。
|
||
//
|
||
// The caller should typically exit with a non-zero code so the process supervisor
|
||
// (systemd, Docker, k8s) can restart the application with the new config.
|
||
//
|
||
// 调用方通常应以非零退出码退出，以便进程管理器（systemd、Docker、k8s）可以使用新配置重启应用程序。
|
||
var ErrReloadRequested = errors.New("reload requested")
|