杭州明婳科技
712 lines
19 KiB
Go
712 lines
19 KiB
Go
package xlgo
|
||
|
||
import (
|
||
"context"
|
||
"errors"
|
||
"fmt"
|
||
"net/http"
|
||
"os"
|
||
"os/signal"
|
||
"strings"
|
||
"sync"
|
||
"syscall"
|
||
"time"
|
||
|
||
"github.com/EthanCodeCraft/xlgo-core/cache"
|
||
"github.com/EthanCodeCraft/xlgo-core/config"
|
||
"github.com/EthanCodeCraft/xlgo-core/database"
|
||
"github.com/EthanCodeCraft/xlgo-core/logger"
|
||
"github.com/EthanCodeCraft/xlgo-core/middleware"
|
||
"github.com/EthanCodeCraft/xlgo-core/response"
|
||
"github.com/EthanCodeCraft/xlgo-core/router"
|
||
"github.com/EthanCodeCraft/xlgo-core/storage"
|
||
|
||
"github.com/gin-gonic/gin"
|
||
"gorm.io/gorm"
|
||
)
|
||
|
||
// Version 框架版本号。发版时只改这一处，避免版本字面量散落各处。
|
||
// CLI（xlgo version）、脚手架生成的 go.mod 等均引用此常量。
|
||
const Version = "1.1.1"
|
||
|
||
// HealthCheckFunc 健康检查函数
|
||
type HealthCheckFunc func(context.Context) error
|
||
|
||
// Migrator 数据库迁移函数
|
||
type Migrator func(*gorm.DB) error
|
||
|
||
// Hook 生命周期钩子。各回调在 App 生命周期的对应阶段被调用：
|
||
// - OnInit: Init() 内组件初始化完成后、路由注册前
|
||
// - OnStart: StartServer() 监听端口前
|
||
// - OnReady: 端口就绪后（已开始接受连接）
|
||
// - OnStop: Shutdown() 开头，关 HTTP 之前
|
||
//
|
||
// OnInit/OnStart/OnReady/OnStop 返回 error 会中断流程并向上返回。
|
||
// A2 修复：OnReady 改为返回 error，失败时触发 shutdown。
|
||
type Hook struct {
|
||
Name string
|
||
OnInit func(*App) error
|
||
OnStart func(*App) error
|
||
OnReady func(*App) error
|
||
OnStop func(*App) error
|
||
}
|
||
|
||
type staticRoute struct {
|
||
relativePath string
|
||
root string
|
||
}
|
||
|
||
// App 应用实例
|
||
type App struct {
|
||
config *config.Config
|
||
configPath string
|
||
configManager *config.Manager
|
||
router *gin.Engine
|
||
registry *router.Registry
|
||
server *http.Server
|
||
|
||
enableLogger bool
|
||
enableMySQL bool
|
||
enableRedis bool
|
||
enableStorage bool
|
||
enableHealth bool
|
||
enableSwagger bool
|
||
enableAutoMigrate bool
|
||
enableLiveness bool
|
||
enableReadiness bool
|
||
enableMetrics bool
|
||
metricsPath string
|
||
|
||
staticRoutes []staticRoute
|
||
migrators []Migrator
|
||
healthChecks []router.HealthCheck
|
||
hooks []Hook
|
||
|
||
// 初始化同步守卫（A1 修复：sync.Once 替代裸 bool，防止并发 Init 竞态）
|
||
initOnce sync.Once
|
||
initErr error
|
||
|
||
// 请求级超时（#19），<=0 表示不启用
|
||
requestTimeout time.Duration
|
||
|
||
// in-flight goroutine 管理（#22）
|
||
rootCtx context.Context // 根 ctx，App.Go 启动的 goroutine 共享
|
||
cancel context.CancelFunc // Shutdown 时 cancel，通知后台任务退出
|
||
wg sync.WaitGroup // 跟踪 App.Go 启动的 goroutine
|
||
}
|
||
|
||
// Option 应用选项
|
||
type Option func(*App)
|
||
|
||
// WithConfigPath 设置配置文件路径
|
||
func WithConfigPath(path string) Option {
|
||
return func(a *App) {
|
||
a.configPath = path
|
||
a.configManager = config.NewManager(path)
|
||
}
|
||
}
|
||
|
||
// WithConfig 设置配置对象。
|
||
// A3 修复：不再调用 config.Set(cfg)，配置仅保留在 App 实例内，不污染全局状态。
|
||
// 依赖 config.Get() 获取注入配置的下游代码请改用 WithConfigPath。
|
||
func WithConfig(cfg *config.Config) Option {
|
||
return func(a *App) {
|
||
a.config = cfg
|
||
}
|
||
}
|
||
|
||
// WithLogger 启用日志
|
||
func WithLogger() Option {
|
||
return func(a *App) { a.enableLogger = true }
|
||
}
|
||
|
||
// WithMySQL 启用 MySQL
|
||
func WithMySQL() Option {
|
||
return func(a *App) { a.enableMySQL = true }
|
||
}
|
||
|
||
// WithRedis 启用 Redis
|
||
func WithRedis() Option {
|
||
return func(a *App) { a.enableRedis = true }
|
||
}
|
||
|
||
// WithStorage 启用文件存储
|
||
func WithStorage() Option {
|
||
return func(a *App) { a.enableStorage = true }
|
||
}
|
||
|
||
// WithHealthRoutes 启用健康检查路由
|
||
func WithHealthRoutes() Option {
|
||
return func(a *App) { a.enableHealth = true }
|
||
}
|
||
|
||
// WithSwaggerRoutes 启用 Swagger 路由
|
||
func WithSwaggerRoutes() Option {
|
||
return func(a *App) { a.enableSwagger = true }
|
||
}
|
||
|
||
// WithDefaultRoutes 启用默认路由（健康检查、Swagger）
|
||
func WithDefaultRoutes() Option {
|
||
return func(a *App) {
|
||
a.enableHealth = true
|
||
a.enableSwagger = true
|
||
}
|
||
}
|
||
|
||
// WithLivenessRoute 启用存活性探针路由 GET /livez（#17）。
|
||
// 永不依赖外部，始终 200，供 K8s livenessProbe。
|
||
func WithLivenessRoute() Option {
|
||
return func(a *App) { a.enableLiveness = true }
|
||
}
|
||
|
||
// WithReadinessRoute 启用就绪性探针路由 GET /readyz（#17）。
|
||
// 复用 healthChecks 检查依赖，失败返回 503，供 K8s readinessProbe。
|
||
func WithReadinessRoute() Option {
|
||
return func(a *App) { a.enableReadiness = true }
|
||
}
|
||
|
||
// WithMetricsRoute 启用 Prometheus 指标端点与采集中间件（#18）。
|
||
// path 默认 /metrics，传入可自定义。
|
||
func WithMetricsRoute(path ...string) Option {
|
||
return func(a *App) {
|
||
a.enableMetrics = true
|
||
if len(path) > 0 && path[0] != "" {
|
||
a.metricsPath = path[0]
|
||
}
|
||
}
|
||
}
|
||
|
||
// WithoutLogger 关闭日志。
|
||
//
|
||
// Without* 系列的定位：xlgo.New() 默认是轻量应用（组件全关），故 Without*
|
||
// 主要用于 NewFullStack / RunFullStack 启用全部组件后，排除个别不需要的项。
|
||
// 例如：xlgo.NewFullStack(xlgo.WithoutSwaggerRoutes()) 全组件但关 Swagger。
|
||
func WithoutLogger() Option {
|
||
return func(a *App) { a.enableLogger = false }
|
||
}
|
||
|
||
// WithoutMySQL 关闭 MySQL
|
||
func WithoutMySQL() Option {
|
||
return func(a *App) { a.enableMySQL = false }
|
||
}
|
||
|
||
// WithoutRedis 关闭 Redis
|
||
func WithoutRedis() Option {
|
||
return func(a *App) { a.enableRedis = false }
|
||
}
|
||
|
||
// WithoutStorage 关闭文件存储
|
||
func WithoutStorage() Option {
|
||
return func(a *App) { a.enableStorage = false }
|
||
}
|
||
|
||
// WithoutWire 已移除（wire 包在 v1.1.0 删除）。保留空函数仅为编译兼容，
|
||
// 调用无副作用。后续版本将删除。
|
||
func WithoutWire() Option {
|
||
return func(a *App) {}
|
||
}
|
||
|
||
|
||
|
||
// WithAutoMigrate 启用数据库迁移（需配合 WithMigrator/WithModels 注册迁移逻辑）
|
||
func WithAutoMigrate() Option {
|
||
return func(a *App) { a.enableAutoMigrate = true }
|
||
}
|
||
|
||
// WithoutAutoMigrate 关闭数据库迁移（即使已通过 WithMigrator/WithModels 注册）
|
||
func WithoutAutoMigrate() Option {
|
||
return func(a *App) { a.enableAutoMigrate = false }
|
||
}
|
||
|
||
// WithoutHealthRoutes 关闭健康检查路由
|
||
func WithoutHealthRoutes() Option {
|
||
return func(a *App) { a.enableHealth = false }
|
||
}
|
||
|
||
// WithoutSwaggerRoutes 关闭 Swagger 路由
|
||
func WithoutSwaggerRoutes() Option {
|
||
return func(a *App) { a.enableSwagger = false }
|
||
}
|
||
|
||
// WithoutDefaultRoutes 关闭默认路由（健康检查、Swagger）
|
||
func WithoutDefaultRoutes() Option {
|
||
return func(a *App) {
|
||
a.enableHealth = false
|
||
a.enableSwagger = false
|
||
}
|
||
}
|
||
|
||
// WithStatic 注册静态文件服务
|
||
func WithStatic(relativePath, root string) Option {
|
||
return func(a *App) {
|
||
a.staticRoutes = append(a.staticRoutes, staticRoute{relativePath: relativePath, root: root})
|
||
}
|
||
}
|
||
|
||
// WithPublicStatic 注册默认 public 静态文件服务
|
||
func WithPublicStatic() Option {
|
||
return WithStatic("/public", "./public")
|
||
}
|
||
|
||
// WithHealthCheck 注册健康检查项
|
||
func WithHealthCheck(name string, check HealthCheckFunc) Option {
|
||
return func(a *App) {
|
||
a.healthChecks = append(a.healthChecks, router.HealthCheck{Name: name, Check: check})
|
||
}
|
||
}
|
||
|
||
// WithMigrator 注册数据库迁移函数（自动启用 AutoMigrate）
|
||
func WithMigrator(m Migrator) Option {
|
||
return func(a *App) {
|
||
if m != nil {
|
||
a.migrators = append(a.migrators, m)
|
||
a.enableAutoMigrate = true
|
||
}
|
||
}
|
||
}
|
||
|
||
// WithHook 注册生命周期钩子（#12）。可多次调用注册多个，按注册顺序触发。
|
||
// 详见 Hook 类型注释。
|
||
func WithHook(h Hook) Option {
|
||
return func(a *App) {
|
||
a.hooks = append(a.hooks, h)
|
||
}
|
||
}
|
||
|
||
// WithRequestTimeout 设置请求级超时（#19）。下游 GORM/Redis 走
|
||
// c.Request.Context() 即可级联取消。d <= 0 不启用。
|
||
func WithRequestTimeout(d time.Duration) Option {
|
||
return func(a *App) { a.requestTimeout = d }
|
||
}
|
||
|
||
// WithModels 注册 GORM 自动迁移模型（自动启用 AutoMigrate）
|
||
func WithModels(models ...any) Option {
|
||
return WithMigrator(func(db *gorm.DB) error {
|
||
return db.AutoMigrate(models...)
|
||
})
|
||
}
|
||
|
||
// WithModules 注册模块
|
||
func WithModules(modules ...router.Module) Option {
|
||
return func(a *App) {
|
||
for _, m := range modules {
|
||
a.registry.RegisterModule(m)
|
||
}
|
||
}
|
||
}
|
||
|
||
// WithVersions 注册版本化 API
|
||
func WithVersions(versions ...*router.VersionedAPI) Option {
|
||
return func(a *App) {
|
||
for _, v := range versions {
|
||
a.registry.RegisterVersion(v)
|
||
}
|
||
}
|
||
}
|
||
|
||
// WithMiddlewares 注册全局中间件
|
||
func WithMiddlewares(middlewares ...gin.HandlerFunc) Option {
|
||
return func(a *App) {
|
||
a.registry.Use(middlewares...)
|
||
}
|
||
}
|
||
|
||
// WithFullStack 启用全功能默认组件
|
||
func WithFullStack() Option {
|
||
return func(a *App) {
|
||
a.enableLogger = true
|
||
a.enableMySQL = true
|
||
a.enableRedis = true
|
||
a.enableStorage = true
|
||
a.enableHealth = true
|
||
a.enableSwagger = true
|
||
a.enableAutoMigrate = true
|
||
// 生产就绪路由（#17/#18）
|
||
a.enableLiveness = true
|
||
a.enableReadiness = true
|
||
a.enableMetrics = true
|
||
a.staticRoutes = append(a.staticRoutes, staticRoute{relativePath: "/public", root: "./public"})
|
||
}
|
||
}
|
||
|
||
// New 创建新应用
|
||
func New(opts ...Option) *App {
|
||
app := &App{}
|
||
app.router = gin.New()
|
||
app.registry = router.NewRegistry(app.router)
|
||
// rootCtx 生命周期与 App 一致，不依赖 Init，使 App.Go 在 Init 前也可用（#22）
|
||
app.rootCtx, app.cancel = context.WithCancel(context.Background())
|
||
|
||
for _, opt := range opts {
|
||
opt(app)
|
||
}
|
||
|
||
return app
|
||
}
|
||
|
||
// NewFullStack 创建启用默认全功能组件的应用
|
||
func NewFullStack(opts ...Option) *App {
|
||
all := append([]Option{WithFullStack()}, opts...)
|
||
return New(all...)
|
||
}
|
||
|
||
// RunFullStack 创建并启动启用默认全功能组件的应用
|
||
func RunFullStack(opts ...Option) error {
|
||
return NewFullStack(opts...).Run()
|
||
}
|
||
|
||
// Init 初始化应用，不启动 HTTP 监听（A1 修复：sync.Once 保证单次执行，并发安全）。
|
||
// 多次调用返回首次执行的结果。
|
||
func (a *App) Init() error {
|
||
a.initOnce.Do(func() { a.initErr = a.doInit() })
|
||
return a.initErr
|
||
}
|
||
|
||
// doInit 执行实际初始化流程。仅在 sync.Once 中调用，不可直接调用。
|
||
func (a *App) doInit() error {
|
||
cfg, err := a.resolveConfig()
|
||
if err != nil {
|
||
return err
|
||
}
|
||
if cfg.IsProduction() {
|
||
gin.SetMode(gin.ReleaseMode)
|
||
}
|
||
|
||
if a.enableLogger {
|
||
if err := logger.Init(cfg); err != nil {
|
||
return fmt.Errorf("初始化日志失败: %w", err)
|
||
}
|
||
}
|
||
|
||
if a.enableMySQL {
|
||
if err := database.InitDB(cfg); err != nil {
|
||
return fmt.Errorf("初始化数据库失败: %w", err)
|
||
}
|
||
a.healthChecks = append(a.healthChecks, router.HealthCheck{Name: "mysql", Check: func(ctx context.Context) error {
|
||
// 优先读探活缓存标记（#21），避免每次探针都同步 ping
|
||
if !database.IsDBHealthy() {
|
||
return errors.New("mysql 主库探活不健康")
|
||
}
|
||
status := database.HealthCheck()
|
||
if !status["master"] {
|
||
return errors.New("mysql 主库不可用")
|
||
}
|
||
return nil
|
||
}})
|
||
}
|
||
|
||
if a.enableRedis {
|
||
if err := database.InitRedis(cfg); err != nil {
|
||
return fmt.Errorf("初始化 Redis 失败: %w", err)
|
||
}
|
||
a.healthChecks = append(a.healthChecks, router.HealthCheck{Name: "redis", Check: database.HealthCheckRedis})
|
||
}
|
||
|
||
if a.enableStorage {
|
||
if err := storage.Init(&cfg.Storage); err != nil {
|
||
return fmt.Errorf("初始化存储失败: %w", err)
|
||
}
|
||
}
|
||
|
||
if a.enableRedis {
|
||
// Redis 就绪后初始化缓存（cache 依赖 Redis 客户端）
|
||
cache.Init()
|
||
}
|
||
|
||
if a.enableAutoMigrate && len(a.migrators) > 0 {
|
||
if !a.enableMySQL {
|
||
return errors.New("注册了数据库迁移但未启用 MySQL")
|
||
}
|
||
db := database.GetDB()
|
||
if db == nil {
|
||
return errors.New("MySQL 未初始化，无法执行数据库迁移")
|
||
}
|
||
for _, migrator := range a.migrators {
|
||
if err := migrator(db); err != nil {
|
||
return fmt.Errorf("数据库迁移失败: %w", err)
|
||
}
|
||
}
|
||
}
|
||
|
||
// 全局中间件链：RequestID 必须最先装入，保证后续 Recovery/日志/响应都能拿到 request_id（#24）
|
||
a.router.Use(middleware.RequestID())
|
||
a.router.Use(middleware.Recover())
|
||
// 请求级超时（#19），配置后装入，下游走 c.Request.Context() 级联取消
|
||
if a.requestTimeout > 0 {
|
||
a.router.Use(middleware.Timeout(a.requestTimeout))
|
||
}
|
||
|
||
for _, staticRoute := range a.staticRoutes {
|
||
a.router.Static(staticRoute.relativePath, staticRoute.root)
|
||
}
|
||
|
||
if a.enableSwagger {
|
||
router.RegisterSwaggerRoutes(a.router)
|
||
}
|
||
if a.enableHealth {
|
||
router.RegisterHealthRoute(a.router, a.healthChecks...)
|
||
}
|
||
if a.enableLiveness {
|
||
router.RegisterLivenessRoute(a.router)
|
||
}
|
||
if a.enableReadiness {
|
||
router.RegisterReadinessRoute(a.router, a.healthChecks...)
|
||
}
|
||
if a.enableMetrics {
|
||
// 采集中间件交给注册中心，Apply 时作为首个全局中间件装入（H8c），
|
||
// 覆盖所有经注册中心注册的业务路由，不依赖调用顺序。
|
||
a.registry.SetMetricsMiddleware(middleware.Metrics())
|
||
if a.metricsPath != "" {
|
||
router.RegisterMetricsRoute(a.router, a.metricsPath)
|
||
} else {
|
||
router.RegisterMetricsRoute(a.router)
|
||
}
|
||
}
|
||
|
||
a.registry.Apply()
|
||
|
||
// 响应模式：默认 business（全 200 + 业务码），可配置 rest（按错误码映射 HTTP status）（#15）
|
||
if mode := strings.TrimSpace(strings.ToLower(a.config.Server.ResponseMode)); mode != "" {
|
||
switch mode {
|
||
case "rest":
|
||
response.SetMode(response.ModeREST)
|
||
case "business":
|
||
response.SetMode(response.ModeBusiness)
|
||
}
|
||
}
|
||
|
||
// in-flight goroutine 根 ctx 在 New() 时已初始化（#22）
|
||
|
||
// 启动主库/从库探活后台循环（#21），ctx 在 Shutdown 时取消
|
||
if a.enableMySQL {
|
||
a.Go(database.StartDBProbing)
|
||
}
|
||
|
||
// OnInit hooks：组件初始化完成后触发（#12）
|
||
for _, h := range a.hooks {
|
||
if h.OnInit != nil {
|
||
if err := h.OnInit(a); err != nil {
|
||
return fmt.Errorf("OnInit hook %q 失败: %w", h.Name, err)
|
||
}
|
||
}
|
||
}
|
||
return nil
|
||
}
|
||
|
||
func (a *App) resolveConfig() (*config.Config, error) {
|
||
if a.config != nil {
|
||
return a.config, nil
|
||
}
|
||
if a.configManager == nil && a.configPath != "" {
|
||
a.configManager = config.NewManager(a.configPath)
|
||
}
|
||
if a.configManager != nil {
|
||
cfg, err := a.configManager.Load()
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
// 让 App 持有的 manager 成为全局默认，
|
||
// 使 config.Get / config.GetString 等便捷函数仍能取到正确配置。
|
||
config.SetDefaultManager(a.configManager)
|
||
a.config = cfg
|
||
return cfg, nil
|
||
}
|
||
cfg := config.Get()
|
||
if cfg == nil {
|
||
return nil, config.ErrConfigNotLoaded
|
||
}
|
||
a.config = cfg
|
||
return cfg, nil
|
||
}
|
||
|
||
// Run 启动应用
|
||
func (a *App) Run() error {
|
||
if err := a.Init(); err != nil {
|
||
return err
|
||
}
|
||
return a.StartServer()
|
||
}
|
||
|
||
// StartServer 启动 HTTP 服务器（支持优雅关闭）
|
||
func (a *App) StartServer() error {
|
||
if a.config == nil {
|
||
return config.ErrConfigNotLoaded
|
||
}
|
||
srvCfg := a.config.Server
|
||
|
||
a.server = &http.Server{
|
||
Handler: a.router,
|
||
ReadTimeout: srvCfg.EffectiveReadTimeout(),
|
||
WriteTimeout: srvCfg.EffectiveWriteTimeout(),
|
||
IdleTimeout: srvCfg.EffectiveIdleTimeout(),
|
||
MaxHeaderBytes: srvCfg.EffectiveMaxHeaderBytes(),
|
||
}
|
||
|
||
useUnix := strings.TrimSpace(srvCfg.UnixSocket) != ""
|
||
if useUnix {
|
||
a.server.Addr = srvCfg.UnixSocket
|
||
} else {
|
||
// Host 为空时监听所有接口（":port"）；设值时绑定指定地址（"host:port"），
|
||
// 用于仅本机（127.0.0.1）或绑定内网网卡的场景
|
||
a.server.Addr = fmt.Sprintf("%s:%d", srvCfg.Host, srvCfg.Port)
|
||
}
|
||
|
||
// OnStart hooks：监听端口前
|
||
for _, h := range a.hooks {
|
||
if h.OnStart != nil {
|
||
if err := h.OnStart(a); err != nil {
|
||
return fmt.Errorf("OnStart hook %q 失败: %w", h.Name, err)
|
||
}
|
||
}
|
||
}
|
||
|
||
serverErr := make(chan error, 1)
|
||
go func() {
|
||
if useUnix {
|
||
logger.Infof("服务器启动，监听 unix socket %s", srvCfg.UnixSocket)
|
||
} else if srvCfg.Host != "" {
|
||
logger.Infof("服务器启动，监听 %s:%d", srvCfg.Host, srvCfg.Port)
|
||
} else {
|
||
logger.Infof("服务器启动，监听端口 %d（所有接口）", srvCfg.Port)
|
||
}
|
||
var err error
|
||
if srvCfg.TLS.Enabled {
|
||
err = a.server.ListenAndServeTLS(srvCfg.TLS.CertFile, srvCfg.TLS.KeyFile)
|
||
} else {
|
||
err = a.server.ListenAndServe()
|
||
}
|
||
if err != nil && !errors.Is(err, http.ErrServerClosed) {
|
||
serverErr <- err
|
||
return
|
||
}
|
||
serverErr <- nil
|
||
}()
|
||
|
||
// OnReady hooks：端口就绪后（A2 修复：失败时触发 shutdown）
|
||
for _, h := range a.hooks {
|
||
if h.OnReady != nil {
|
||
if err := h.OnReady(a); err != nil {
|
||
logger.Errorf("OnReady hook %q 失败: %v", h.Name, err)
|
||
serverErr <- fmt.Errorf("OnReady hook %q 失败: %w", h.Name, err)
|
||
return fmt.Errorf("OnReady hook %q 失败: %w", h.Name, err)
|
||
}
|
||
}
|
||
}
|
||
|
||
quit := make(chan os.Signal, 1)
|
||
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM, syscall.SIGHUP)
|
||
defer signal.Stop(quit)
|
||
|
||
select {
|
||
case err := <-serverErr:
|
||
if err != nil {
|
||
return fmt.Errorf("服务器启动失败: %w", err)
|
||
}
|
||
return nil
|
||
case sig := <-quit:
|
||
logger.Infof("收到信号 %v，开始优雅关闭...", sig)
|
||
return a.Shutdown()
|
||
}
|
||
}
|
||
|
||
// Shutdown 优雅关闭应用
|
||
func (a *App) Shutdown() error {
|
||
shutdownTimeout := 30 * time.Second
|
||
if a.config != nil {
|
||
shutdownTimeout = a.config.Server.EffectiveShutdownTimeout()
|
||
}
|
||
ctx, cancel := context.WithTimeout(context.Background(), shutdownTimeout)
|
||
defer cancel()
|
||
|
||
var errs []error
|
||
|
||
// OnStop hooks：关 HTTP 之前触发（#12）
|
||
for _, h := range a.hooks {
|
||
if h.OnStop != nil {
|
||
if err := h.OnStop(a); err != nil {
|
||
errs = append(errs, fmt.Errorf("OnStop hook %q 失败: %w", h.Name, err))
|
||
}
|
||
}
|
||
}
|
||
|
||
// 取消根 ctx，通知 App.Go 启动的后台 goroutine 退出（#22）
|
||
if a.cancel != nil {
|
||
a.cancel()
|
||
}
|
||
|
||
if a.server != nil {
|
||
logger.Info("关闭 HTTP 服务器...")
|
||
if err := a.server.Shutdown(ctx); err != nil {
|
||
logger.Warnf("HTTP 服务器关闭超时: %v", err)
|
||
errs = append(errs, err)
|
||
if closeErr := a.server.Close(); closeErr != nil {
|
||
errs = append(errs, closeErr)
|
||
}
|
||
}
|
||
}
|
||
|
||
// 等待业务 in-flight goroutine 退出（#22），受 shutdownTimeout 约束
|
||
waitDone := make(chan struct{})
|
||
go func() {
|
||
a.wg.Wait()
|
||
close(waitDone)
|
||
}()
|
||
select {
|
||
case <-waitDone:
|
||
case <-ctx.Done():
|
||
logger.Warnf("等待后台 goroutine 退出超时")
|
||
}
|
||
|
||
logger.Info("停止限流器...")
|
||
middleware.StopRateLimiters()
|
||
|
||
logger.Info("关闭数据库连接...")
|
||
if err := database.CloseAll(); err != nil {
|
||
errs = append(errs, err)
|
||
}
|
||
if err := database.CloseRedis(); err != nil {
|
||
errs = append(errs, err)
|
||
}
|
||
|
||
logger.Info("关闭日志...")
|
||
// 先记录最后一条 "应用已优雅关闭"，再 Close（关闭后写日志会 fall back 到 nop）
|
||
logger.Info("应用已优雅关闭")
|
||
if err := logger.Close(); err != nil {
|
||
errs = append(errs, err)
|
||
}
|
||
return errors.Join(errs...)
|
||
}
|
||
|
||
// Go 启动一个受 App 生命周期管理的后台 goroutine（#22）。
|
||
// fn 收到的 ctx 在 Shutdown 时被 cancel，fn 应在 ctx.Done() 时及时退出。
|
||
// Shutdown 会等待所有 App.Go 启动的 goroutine 退出（带 ShutdownTimeout 超时）。
|
||
func (a *App) Go(fn func(ctx context.Context)) {
|
||
if fn == nil {
|
||
return
|
||
}
|
||
ctx := a.rootCtx
|
||
if ctx == nil {
|
||
ctx = context.Background()
|
||
}
|
||
a.wg.Add(1)
|
||
go func() {
|
||
defer a.wg.Done()
|
||
fn(ctx)
|
||
}()
|
||
}
|
||
|
||
// GetRegistry 获取路由注册中心（用于动态注册）
|
||
func (a *App) GetRegistry() *router.Registry {
|
||
return a.registry
|
||
}
|
||
|
||
// GetRouter 获取 Gin Engine（用于高级自定义）
|
||
func (a *App) GetRouter() *gin.Engine {
|
||
return a.router
|
||
}
|
||
|
||
// GetServer 获取 HTTP Server（用于高级自定义）
|
||
func (a *App) GetServer() *http.Server {
|
||
return a.server
|
||
}
|