// Package app 应用启动器(Day 12):统一装配 配置/日志/DB/Redis/Kafka/追踪/HTTP, // 提供配置热更新(ETCD watch)与优雅停机(反向依序释放)。 // 组件连接失败采用降级策略(Warn 并继续),保障 /health 始终可用。 package app import ( "context" "errors" "flag" "fmt" "net/http" "os" "os/signal" "sync" "syscall" "time" "github.com/gin-gonic/gin" clientv3 "go.etcd.io/etcd/client/v3" "go.uber.org/zap" "gorm.io/gorm" "go-sms/internal/config" "go-sms/internal/middleware" "go-sms/internal/pkg/cache" "go-sms/internal/pkg/logger" "go-sms/internal/pkg/metrics" "go-sms/internal/pkg/queue" "go-sms/internal/repository/mysql" ) // Options 启动选项。 type Options struct { ConfigPath string // 配置文件路径(空则走默认解析规则) ServiceName string // 服务名(tracer/日志标识) Version string // 构建注入版本 Commit string // 构建注入提交 RegisterRoutes func(r *gin.Engine, a *App) // 业务路由钩子(阶段 2+;可经 a 取 DB 等依赖) } // App 应用实例:持有全部组件句柄,负责生命周期。 type App struct { cfg *config.Config lg *zap.Logger httpSrv *http.Server db *gorm.DB // nil = 降级 redis *cache.Client // nil = 降级 producer *queue.Producer // nil = 降级 etcdCli *clientv3.Client watchCancel context.CancelFunc tracerShutdown func(context.Context) error mu sync.Mutex // 保护 shutdownHooks shutdownHooks []func() // 停机钩子(Day 27:定时任务随优雅停机退出) } // New 装配应用:配置 → 日志 → 追踪 → DB/Redis/Kafka(降级)→ HTTP → 热更新。 func New(opts Options) (*App, error) { cfg, err := config.Load(opts.ConfigPath) if err != nil { return nil, err } if err := logger.Init(logger.Options{ Level: cfg.Log.Level, Format: cfg.Log.Format, Output: cfg.Log.Output, File: logger.FileOptions{ Path: cfg.Log.File.Path, MaxSizeMB: cfg.Log.File.MaxSizeMB, MaxAgeDays: cfg.Log.File.MaxAgeDays, MaxBackups: cfg.Log.File.MaxBackups, Compress: cfg.Log.File.Compress, }, }); err != nil { return nil, fmt.Errorf("app: 初始化日志失败: %w", err) } lg := logger.L() a := &App{cfg: cfg, lg: lg} lg.Info("app_assembling", zap.String("service", opts.ServiceName), zap.String("version", opts.Version), zap.String("config_source", cfg.Source)) // 链路追踪(失败降级) if cfg.Tracer.Enabled { if sd, err := middleware.InitTracer(context.Background(), cfg.Tracer.OTLPEndpoint, cfg.Tracer.ServiceName); err != nil { lg.Warn("tracer_init_failed_degraded", zap.Error(err)) } else { a.tracerShutdown = sd } } // MySQL(失败降级) if db, err := mysql.Open(cfg.MySQL.DSN, mysql.PoolOptions{ MaxOpenConns: cfg.MySQL.MaxOpenConns, MaxIdleConns: cfg.MySQL.MaxIdleConns, ConnMaxLifetime: cfg.MySQL.ConnMaxLifetime, SlowThresholdMs: cfg.MySQL.SlowThresholdMs, }); err != nil { lg.Warn("mysql_init_failed_degraded", zap.Error(err)) } else { pingCtx, cancel := context.WithTimeout(context.Background(), 3*time.Second) if err := mysql.Ping(pingCtx, db); err != nil { lg.Warn("mysql_ping_failed_degraded", zap.Error(err)) } else { lg.Info("mysql_connected", zap.String("dsn", maskDSN(cfg.MySQL.DSN))) } cancel() a.db = db } // Redis(失败降级) if rc, err := cache.New(cache.Options{ Mode: cfg.Redis.Mode, Addrs: cfg.Redis.Addrs, Password: cfg.Redis.Password, DB: cfg.Redis.DB, PoolSize: cfg.Redis.PoolSize, }); err != nil { lg.Warn("redis_init_failed_degraded", zap.Error(err)) } else { a.redis = rc lg.Info("redis_connected", zap.Strings("addrs", cfg.Redis.Addrs), zap.String("mode", cfg.Redis.Mode)) } // Kafka 生产者(失败降级) if p, err := queue.NewProducer(queue.ProducerConfig{Brokers: cfg.Kafka.Brokers, Logger: lg}); err != nil { lg.Warn("kafka_producer_init_failed_degraded", zap.Error(err)) } else { a.producer = p lg.Info("kafka_producer_connected", zap.Strings("brokers", cfg.Kafka.Brokers)) } // HTTP 引擎:请求日志 → 限流 → Recovery → /health(+业务路由) if os.Getenv("GIN_MODE") == "" { gin.SetMode(gin.ReleaseMode) } engine := gin.New() engine.Use(middleware.Logger(lg), middleware.Recovery(lg), middleware.Metrics()) if a.tracerShutdown != nil { engine.Use(middleware.Tracer(cfg.Tracer.ServiceName)) } if cfg.RateLimit.Enabled && a.redis != nil { rlCfg := middleware.RateLimitConfig{Capacity: cfg.RateLimit.Capacity, Rate: cfg.RateLimit.RatePerSec} if cfg.RateLimit.Key == "ip" { rlCfg.KeyFunc = middleware.ByClientIP } engine.Use(middleware.RateLimit(a.redis, rlCfg)) } middleware.HealthRegister(engine) // /metrics:Prometheus 抓取端点(生产建议集群内访问/加白名单) engine.GET("/metrics", gin.WrapH(metrics.Handler())) if opts.RegisterRoutes != nil { opts.RegisterRoutes(engine, a) } a.httpSrv = &http.Server{ Addr: cfg.Server.HTTP.Addr, Handler: engine, ReadTimeout: cfg.Server.HTTP.ReadTimeout, WriteTimeout: cfg.Server.HTTP.WriteTimeout, } // 配置热更新(ETCD watch;失败降级) if cfg.HotReload.Enabled { if cli, err := clientv3.New(clientv3.Config{Endpoints: cfg.ETCD.Endpoints, DialTimeout: 5 * time.Second}); err != nil { lg.Warn("etcd_init_failed_hotreload_degraded", zap.Error(err)) } else { a.etcdCli = cli w := config.NewETCDWatcher(cli, cfg.HotReload.Prefix, cfg.Source, a.onConfigReload, lg) wctx, wcancel := context.WithCancel(context.Background()) a.watchCancel = wcancel go func() { if err := w.Run(wctx); err != nil { lg.Warn("etcd_watcher_exited", zap.Error(err)) } }() lg.Info("hotreload_enabled", zap.String("prefix", cfg.HotReload.Prefix), zap.Strings("etcd", cfg.ETCD.Endpoints)) } } return a, nil } // onConfigReload 热更新回调:日志级别即时生效;其余项更新内存配置(连接类需重启)。 func (a *App) onConfigReload(cfg *config.Config) { if level, err := zap.ParseAtomicLevel(cfg.Log.Level); err == nil { logger.Level().SetLevel(level.Level()) } a.cfg = cfg } // DB 返回 MySQL 连接(可能为 nil:降级态;业务装配前判空)。 func (a *App) DB() *gorm.DB { return a.db } // Redis 返回 Redis 客户端(可能为 nil:降级态;业务装配前判空)。 func (a *App) Redis() *cache.Client { return a.redis } // Config 返回当前配置(热更新后为最新)。 func (a *App) Config() *config.Config { return a.cfg } // Lg 返回全局日志器(业务装配/降级告警用)。 func (a *App) Lg() *zap.Logger { return a.lg } // Producer Day 46:Kafka 生产者(可 nil=未装配降级;调用方自行判空)。 func (a *App) Producer() *queue.Producer { return a.producer } // OnShutdown 注册停机钩子(注册顺序执行;定时任务/后台协程随优雅停机退出)。 func (a *App) OnShutdown(fn func()) { if fn == nil { return } a.mu.Lock() defer a.mu.Unlock() a.shutdownHooks = append(a.shutdownHooks, fn) } // Run 启动 HTTP 并阻塞直至 SIGINT/SIGTERM,随后优雅停机。 func (a *App) Run() error { errCh := make(chan error, 1) go func() { a.lg.Info("http_server_started", zap.String("addr", a.cfg.Server.HTTP.Addr), zap.String("endpoint", "GET /health")) if err := a.httpSrv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) { errCh <- err } }() quit := make(chan os.Signal, 1) signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM) select { case err := <-errCh: return fmt.Errorf("app: HTTP 服务异常: %w", err) case sig := <-quit: a.lg.Info("shutdown_signal_received", zap.Stringer("signal", sig)) } a.Shutdown(10 * time.Second) return nil } // Shutdown 优雅停机:HTTP 等待在途请求 → 停热更新 → 逆序释放组件 → 日志落盘。 func (a *App) Shutdown(grace time.Duration) { ctx, cancel := context.WithTimeout(context.Background(), grace) defer cancel() if err := a.httpSrv.Shutdown(ctx); err != nil { a.lg.Error("http_shutdown_failed", zap.Error(err)) } else { a.lg.Info("http_server_stopped") } if a.watchCancel != nil { a.watchCancel() a.lg.Info("hotreload_stopped") } // 业务停机钩子(定时任务等;注册序执行) a.mu.Lock() hooks := append([]func(){}, a.shutdownHooks...) a.mu.Unlock() for _, fn := range hooks { fn() } if a.producer != nil { if err := a.producer.Close(); err != nil { a.lg.Error("kafka_producer_close_failed", zap.Error(err)) } else { a.lg.Info("kafka_producer_closed") } } if a.redis != nil { _ = a.redis.Close() a.lg.Info("redis_closed") } if a.db != nil { if err := mysql.Close(a.db); err != nil { a.lg.Error("mysql_close_failed", zap.Error(err)) } else { a.lg.Info("mysql_closed") } } if a.etcdCli != nil { _ = a.etcdCli.Close() } if a.tracerShutdown != nil { if err := a.tracerShutdown(context.Background()); err != nil { a.lg.Warn("tracer_shutdown_failed", zap.Error(err)) } } logger.Sync() a.lg.Info("app_stopped_gracefully") } // maskDSN 密码脱敏。 func maskDSN(dsn string) string { for i := 0; i < len(dsn); i++ { if dsn[i] == ':' { for j := i + 1; j < len(dsn); j++ { if dsn[j] == '@' { return dsn[:i+1] + "***" + dsn[j:] } } break } } return dsn } // Main 便捷入口// Main 便捷入口:flag 解析 + New + Run(cmd/*/main.go 薄壳)。 func Main(opts Options) { configPath := flag.String("config", os.Getenv(config.EnvKeyFile), "配置文件路径(留空则依次取环境变量 GOSMS_CONFIG、configs/config.dev.yaml)") flag.Parse() opts.ConfigPath = *configPath a, err := New(opts) if err != nil { fmt.Fprintf(os.Stderr, "[%s] 启动失败: %v\n", opts.ServiceName, err) os.Exit(1) } if err := a.Run(); err != nil { fmt.Fprintf(os.Stderr, "[%s] 运行异常退出: %v\n", opts.ServiceName, err) os.Exit(1) } }