直接用 pgx 原生接口 + pgxpool 是 Go 微服务对接 PostgreSQL 的高性能标准做法，混用 database/sql 会损失 35%～60% QPS 并丧失 LISTEN/NOTIFY、COPY 等关键能力；pgxpool 必须显式配置健康检查、生命周期及会话参数；批量操作必须用 pgx.Batch；时间字段必须全程使用 timestamptz + UTC。
直接用 pgx 原生接口（不是 database/sql）+ pgxpool 连接池，是当前 Go 微服务对接 PostgreSQL 的高性能标准做法。 混用 database/sql 适配层会损失 35%～60% QPS，且无法使用 LISTEN/NOTIFY、COPY、流式查询等关键能力。
为什么不能用 database/sql + pgx 驱动做高性能底座
虽然 _ "github.com/jackc/pgx/v5/database/sql" 能让 pgx 兼容 sql.DB，但它本质仍是绕过原生协议的“翻译层”：所有 rows.Scan() 都要走反射 + 类型转换，time.Time 和 jsonb 映射不准，NULL 值容易 panic；更关键的是，它完全屏蔽了 pgx.Conn 独有的二进制协议直通能力。微服务对延迟敏感，这种抽象代价不可接受。
- 常见错误现象：
Scan() into *string from jsonb报错，或time.Time字段始终为零值 - 使用场景：高频用户查询（如 /user/{id}）、实时通知推送（需
LISTEN）、日志批量写入（需COPY） - 性能影响：同等负载下 CPU 占用高 40%，连接复用率下降，健康检查失效
pgxpool 连接池必须显式配置健康检查与生命周期
默认的 pgxpool.New() 不启用健康检查，连接池里会悄悄积压 stale connection——数据库重启、网络抖动后，请求持续失败直到超时。生产环境必须用 pgxpool.ParseConfig 手动控制参数。
-
HealthCheckPeriod设为30 * time.Second，否则空闲连接断连后不会自动剔除 -
MaxConnLifetime设为58 * time.Minute（避开 PostgreSQL 默认60min的tcp_keepalives_idle），防连接被服务端静默关闭 - 在
AfterConnect回调里执行SET application_name = 'auth-service'和SET timezone = 'UTC'，确保会话上下文一致 - 避免设
MinConns > 0后不预热，冷启动时第一批请求会卡在连接创建上
批量操作必须用 pgx.Batch，别拼 SQL 字符串
单条 INSERT 在 1000 QPS 下会因 TCP 往返和 PostgreSQL 解析开销成为瓶颈；手拼 SQL 字符串还可能触发 SQL 注入或类型错位。pgx.Batch 将多语句打包成单次二进制协议请求，复用同一连接上下文。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
立即学习“go语言免费学习笔记（深入）”；
- batch 大小建议 100～200 条，超过 500 条易触发 PostgreSQL 的
max_stack_depth - 不要用
pool.Query()循环插入，那是反模式；正确路径是pool.SendBatch(ctx, batch)→br.Exec() - 每条语句结果必须单独调用
br.Exec()或br.Query()获取，否则后续语句阻塞 - 注意
pgx.Batch不支持事务嵌套，如需原子性，整个 batch 必须包裹在tx.Begin()内
时间字段必须用 timestamptz + UTC，且禁止在应用层做时区转换
PostgreSQL 的 timestamp（无时区）在跨时区部署时必然错乱；Go 的 time.Local 会受服务器系统时区影响，导致 created_at 存入和读出不一致。唯一可靠方案是全程用 timestamptz 并强制会话级 UTC。
- 建表时所有时间字段声明为
timestamptz，而非timestamp - 连接池
AfterConnect中执行SET timezone = 'UTC'，而非依赖time.Now().UTC() - Go 代码中一律用
time.Time（非指针），pgx 会自动按timestamptz解析；若字段可空，用*time.Time，但需确认 DB 默认值不是NULL - 前端传来的 ISO 时间字符串（如
"2026-06-30T16:04:00+08:00"）应由 API 层统一转为 UTC 后再入库，不在 SQL 层用AT TIME ZONE
最常被忽略的一点：pgxpool 实例必须全局复用且 defer pool.Close()，但微服务中容易在每个 handler 里重复 New()；另外，pgx.Conn 不能跨 goroutine 复用，pool.Acquire() 后必须配对 Release()，漏掉一次就会永久占用连接。
