Go context 实战：从优雅退出到数据库连接超时

1main → run → database.Init → PingContext → 底层网络读

1context.Background()          ← 根，永不取消
2    │
3    └─(NotifyContext)──► ctx          ← 收到 Ctrl+C / SIGTERM 时取消
4            │
5            └─(WithTimeout)──► pingCtx ← 父取消 或 5s 到点，先到先取消

1type Context interface {
2    Deadline() (deadline time.Time, ok bool) // 有截止时间吗
3    Done() <-chan struct{}                   // 取消信号 channel
4    Err() error                              // 取消原因：Canceled / DeadlineExceeded / nil
5    Value(key any) any                       // 取携带的值
6}

1func DoSomething(ctx context.Context, id int) error { ... } // ✅
2func (s *Svc) DoSomething(id int) error { s.ctx ... }        // ❌ 不要存 ctx

1ctx, cancel := context.WithTimeout(parent, 5*time.Second)
2// ↑ 执行时间 ≈ 0，只是「设了个闹钟」，马上返回
3
4err := db.PingContext(ctx)
5// ↑ 这里才真正阻塞，才可能等到 5 秒上限

1ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
2defer stop()

1Ctrl+C → ctx 取消 → <-ctx.Done() 返回 → 打印退出日志 → defer 清理 → run 返回 → main 返回 → 进程退出

 1func main() {
 2    // 结构化日志统一走 JSON，便于日志采集（stdout）。
 3    // level 用 LevelVar，方便读到配置后按 mode 动态调整。
 4    level := new(slog.LevelVar)
 5    level.Set(slog.LevelInfo)
 6    slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
 7        Level: level,
 8    })))
 9
10    // 监听 Ctrl+C（os.Interrupt）和 kill（SIGTERM），
11    // 收到信号后 ctx 被取消，作为整个进程优雅退出的触发点。
12    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
13    defer stop()
14
15    if err := run(ctx, level); err != nil {
16        // slog 没有内置 Fatal，这里手动 Error + os.Exit。
17        slog.Error("启动失败", "err", err)
18        os.Exit(1)
19    }
20}
21
22func run(ctx context.Context, level *slog.LevelVar) error {
23    // ... 读配置（flag/config.Load）...
24
25    db, err := database.Init(ctx, &cfg.Database) // ctx 一路透传
26    if err != nil {
27        return err
28    }
29    defer db.Close()
30
31    slog.Info("数据库连接成功",
32        "dbname", cfg.Database.DBName,
33        "port", cfg.Database.Port,
34    )
35
36    slog.Info("服务启动成功",
37        "app_name", cfg.Server.AppName,
38        "port", cfg.Server.Port,
39    )
40
41    // TODO: 这里后续启动 HTTP server 等服务。
42    // 目前先阻塞等待退出信号，保证优雅退出流程可用。
43    <-ctx.Done()
44
45    slog.Info("收到退出信号，开始优雅退出")
46    // TODO: 后续接入 HTTP 时，在此用带超时的 context 调用 server.Shutdown，
47    // 例如：
48    //   shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
49    //   defer cancel()
50    //   if err := srv.Shutdown(shutdownCtx); err != nil { ... }
51    // 注意：不能用已取消的 ctx，否则 Shutdown 会立即返回。
52
53    // 下方 defer（db.Close 等）会在这里按 LIFO 顺序执行。
54    return nil
55}

1<-ctx.Done()

1defer A()   // 先注册
2defer B()   // 后注册
3...
4return      // 执行顺序：B 先、A 后（LIFO）

1<-ctx.Done()          // 此刻 ctx 已经被取消
2srv.Shutdown(ctx)     // ❌ 错！用已取消的 ctx，Shutdown 立即返回，等于没优雅

1<-ctx.Done()
2
3shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
4defer cancel()
5if err := srv.Shutdown(shutdownCtx); err != nil { // ✅ 给在途请求最多 10 秒处理完
6    slog.Error("HTTP 优雅关闭失败", "err", err)
7}

 1const connTimeout = 5 * time.Second
 2
 3// Init 初始化数据库连接池并做一次连通性探测。
 4// ctx 用于控制建连阶段的取消/超时（例如进程启动时收到退出信号）。
 5func Init(ctx context.Context, cfg *config.Database) (*sqlx.DB, error) {
 6    // Open 只创建连接池、不会真正建连，因此这里不会返回连接错误。
 7    db, err := sqlx.Open("mysql", cfg.DSN())
 8    if err != nil {
 9        return nil, fmt.Errorf("database: 打开数据库 %s 失败: %w", cfg.DBName, err)
10    }
11
12    db.SetMaxOpenConns(cfg.MaxOpenConns)
13    db.SetMaxIdleConns(cfg.MaxIdleConns)
14    db.SetConnMaxLifetime(time.Duration(cfg.ConnMaxLifetimeMin) * time.Minute)
15
16    // 真正的建连发生在 Ping，用带超时的 ctx 兜底。
17    pingCtx, cancel := context.WithTimeout(ctx, connTimeout)
18    defer cancel()
19    if err := db.PingContext(pingCtx); err != nil {
20        // Ping 失败时关闭连接池，避免资源泄漏（返回值是 nil，调用方不会 Close）。
21        _ = db.Close()
22        return nil, fmt.Errorf("database: 数据库 %s 连接失败: %w", cfg.DBName, err)
23    }
24
25    return db, nil
26}

 1// Connect = Open + Ping
 2func Connect(driverName, dataSourceName string) (*DB, error) {
 3    db, err := Open(driverName, dataSourceName) // 第一步
 4    if err != nil {
 5        return nil, err
 6    }
 7    err = db.Ping()                             // 第二步：试连（无 ctx）
 8    if err != nil {
 9        db.Close()
10        return nil, err
11    }
12    return db, nil
13}

1db, _ := sqlx.Open("mysql", dsn)   // 此刻还没连
2db.Exec("INSERT ...")              // 这一行执行时，池子才自动去连数据库

1Ping       ↔ PingContext
2Query      ↔ QueryContext
3Exec       ↔ ExecContext
4QueryRow   ↔ QueryRowContext
5Prepare    ↔ PrepareContext
6Begin      ↔ BeginTx

1pingCtx, cancel := context.WithTimeout(ctx, connTimeout) // 设闹钟，秒返回
2defer cancel()
3err := db.PingContext(pingCtx)                            // 睡觉等人叫醒

 1main: ctx = 信号ctx（无超时）
 2  │
 3  └─► Init(ctx, cfg)
 4        │
 5        ├─ Open(DSN)                     ← 只建空池，不连接
 6        ├─ 设置连接池参数
 7        ├─ pingCtx = WithTimeout(ctx,5s) ← 子ctx：信号 或 5秒，先到先取消
 8        ├─ PingContext(pingCtx)          ← 这里才真正 TCP 连接
 9        │      ├─ 成功 ──────► return db ✅（main 随后 defer db.Close()）
10        │      ├─ 5s 超时 ───► err=DeadlineExceeded ─► db.Close() ─► return err ❌
11        │      └─ Ctrl+C ───► err=Canceled         ─► db.Close() ─► return err ❌
12        └─ defer cancel()  ← 无论成败，拆掉定时器

1db, err := database.Init(ctx, &cfg.Database)
2if err != nil {
3    return err        // ← 这里拿不到 db，不会 defer db.Close()
4}
5defer db.Close()      // ← 只有成功才注册

1context.Background()                       // 根，永不取消
2context.TODO()                             // 占位
3context.WithCancel(parent)                 // (ctx, cancel)
4context.WithTimeout(parent, 5*time.Second) // (ctx, cancel) 常用
5context.WithDeadline(parent, t)            // (ctx, cancel)
6context.WithValue(parent, key, val)        // ctx
7context.WithoutCancel(parent)              // 不随父取消，保留 value

1ctx.Done()                     // <-chan struct{}
2ctx.Err()                      // nil / Canceled / DeadlineExceeded
3ctx.Deadline()                 // (time.Time, bool)
4<-ctx.Done()                   // 阻塞等待取消
5context.Cause(ctx)             // 取具体取消原因

1ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
2defer stop()

1db.Ping()               ↔ db.PingContext(ctx)
2db.Query(...)           ↔ db.QueryContext(ctx, ...)
3db.Exec(...)            ↔ db.ExecContext(ctx, ...)
4db.QueryRow(...)        ↔ db.QueryRowContext(ctx, ...)
5db.Prepare(...)         ↔ db.PrepareContext(ctx, ...)
6db.Begin()              ↔ db.BeginTx(ctx, opts)

 1// main：优雅退出触发点
 2ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 3defer stop()
 4if err := run(ctx, level); err != nil { slog.Error("启动失败", "err", err); os.Exit(1) }
 5
 6// run：阻塞等信号，然后 defer 清理
 7<-ctx.Done()
 8
 9// database.Init：带超时的建连探测
10pingCtx, cancel := context.WithTimeout(ctx, connTimeout)
11defer cancel()
12if err := db.PingContext(pingCtx); err != nil { _ = db.Close(); return nil, err }