Go HTTP处理器中pgx使用context的正确方法及报错解决

云上老周

2026-8-31

问题验证结论

更新1：测试确认，选择不同的父context会直接影响报错表现：

// 该写法可正常运行，无'context canceled'错误
ctx, cancel := context.WithTimeout(context.Background(), 100*time.Second)

// 但该写法在轻度负载下会产生'context canceled'错误
// ctx, cancel := context.WithTimeout(r.Context(), 100*time.Second)

defer cancel()
app.Insert(ctx, record)

下方提供可复现问题的完整独立示例。

问题现象

Go HTTP接口开发中出现如下异常：

首次请求接口时返回context cancelled错误，但数据实际已经成功插入数据库
后续请求接口无报错，数据可正常写入
访问localhost:4444/create接口时按住Ctrl+R快速刷新制造轻度负载，即可稳定复现该报错

核心疑问：HTTP处理器与pgx的QueryRow方法之间传递context的方式是否正确？对应的最佳实践是什么？

可复现问题的完整代码如下，保存为main.go后执行go run main.go即可启动服务：

package main

import (
    "context"
    "fmt"
    "log"
    "math/rand"
    "net/http"
    "time"

    "github.com/jackc/pgx/v4/pgxpool"
)

type application struct {
    DB *pgxpool.Pool
}

type Task struct {
    ID     string
    Name   string
    Status string
}

//HTTP GET /create
func (app *application) create(w http.ResponseWriter, r *http.Request) {
    fmt.Println(r.URL.Path, time.Now())
    task := &Task{Name: fmt.Sprintf("Task #%d", rand.Int()%1000), Status: "pending"}
    // -------- 问题代码段 ----
    // 该行可正常运行，不会产生'context canceled'错误
    //ctx, cancel := context.WithTimeout(context.Background(), 100*time.Second)
    // 该行在轻度负载下会产生'context canceled'错误
    ctx, cancel := context.WithTimeout(r.Context(), 100*time.Second)
    // -------- 代码段结束 -------
    defer cancel()
    err := app.insertTask(ctx, task)
    if err != nil {
        fmt.Println("insert error:", err)
        return
    }
    fmt.Fprintf(w, "%+v", task)
}
func (app *application) insertTask(ctx context.Context, t *Task) error {
    stmt := `INSERT INTO task (name, status) VALUES ($1, $2) RETURNING ID`
    row := app.DB.QueryRow(ctx, stmt, t.Name, t.Status)
    err := row.Scan(&t.ID)
    if err != nil {
        return err
    }
    return nil
}

func main() {
    rand.Seed(time.Now().UnixNano())
    db, err := pgxpool.Connect(context.Background(), "postgres://test:test123@localhost:5432/test")
    if err != nil {
        log.Fatal(err)
    }
    log.Println("db conn pool created")
    stmt := `CREATE TABLE IF NOT EXISTS public.task (
        id uuid NOT NULL DEFAULT gen_random_uuid(),
        name text NULL,
        status text NULL,
        PRIMARY KEY (id)
     ); `
    _, err = db.Exec(context.Background(), stmt)
    if err != nil {
        log.Fatal(err)
    }
    log.Println("task table created")
    defer db.Close()
    app := &application{
        DB: db,
    }
    mux := http.NewServeMux()
    mux.HandleFunc("/create", app.create)

    log.Println("http server up at localhost:4444")
    err = http.ListenAndServe(":4444", mux)
    if err != nil {
        log.Fatal(err)
    }
}

原因说明

这个报错不是pgx的bug，完全符合Go context的标准设计逻辑：

每个HTTP请求自带的r.Context()生命周期和请求强绑定，当客户端主动断开连接（比如快速刷新时浏览器直接取消上一个未完成的请求）、服务端已经把响应全部写回客户端时，这个context会立刻触发取消信号。
快速刷新场景下，前一个请求还没等到数据库返回结果就被浏览器中断，pgx在等待查询结果时收到context取消信号，就会抛出context canceled错误。
出现“报错但数据插入成功”的现象，是因为INSERT语句已经发送到PostgreSQL服务端并执行完成，只是结果返回的环节被中断，数据库操作本身已经正常提交。
首次请求更容易触发报错，是因为首次请求时pgx连接池需要完成初始化建连、表结构检查等额外操作，整体接口耗时更长，被刷新动作打断的概率更高。

最佳实践

传递context没有绝对的对错，要匹配业务场景选择：

对于不可中断的核心操作（比如资金流水记录、支付状态更新、回调数据落库），不要直接使用请求context作为父节点，应该基于context.Background()派生带超时的独立context，避免客户端断开导致核心操作被意外中断，引发数据不一致问题。
对于可随请求终止的非核心操作（比如普通列表查询、用户实时搜索、非关键信息上报），应该传递基于r.Context()派生的context，请求终止时可以立刻中断数据库操作、释放连接资源，避免无效的资源占用。
无论选择哪种父context，都必须给数据库操作设置合理的超时时间，禁止使用无超时的context，避免慢查询耗尽连接池。

内容的提问来源于stack exchange，提问作者lifebythedrop