本文深入剖析 go 应用中因 database/sql 自动重试机制与连接异常（如 ssl 错误）导致的“duplicate key violates unique constraint”误报问题，并提供基于事务、幂等性校验和连接配置优化的生产级解决方案。
本文深入剖析 go 应用中因 database/sql 自动重试机制与连接异常（如 ssl 错误）导致的“duplicate key violates unique constraint”误报问题，并提供基于事务、幂等性校验和连接配置优化的生产级解决方案。
在 Go 应用中向 PostgreSQL 插入数据时，即使已在内存中通过 map[string]bool 去重并严格校验哈希值，仍偶发出现 pq: duplicate key value violates unique constraint "bd_hash_index" 错误——这看似违背逻辑，实则暴露了底层驱动与 SQL 执行模型的关键细节。
根本原因在于：*`sql.DB.Exec()在遇到driver.ErrBadConn（如网络中断、SSL 握手失败、连接被服务端关闭）时，默认会自动重试最多 10 次**（由maxBadConnRetries控制）。而lib/pq驱动在某些 SSL 异常场景（如 TLS 重协商失败）下，可能错误地返回ErrBadConn，即使前一次INSERT` 实际已成功提交到数据库。此时重试将再次执行相同语句，触发唯一索引冲突。
更关键的是，database/sql 的自动重试不保证幂等性——它无法判断上一次操作是否已被数据库执行。因此，看似“安全”的内存去重，在并发或网络不稳定场景下完全失效。
✅ 正确实践：使用显式事务 + ON CONFLICT
避免依赖内存状态，转而利用 PostgreSQL 原生的原子性能力：
func (pr *Process) insertBodyWithConflictHandling(
hash, typ, source, bodyStr string,
createdTs int64,
) error {
tx, err := pr.DB.Begin()
if err != nil {
return err
}
defer tx.Rollback() // 确保失败时回滚
_, err = tx.Exec(
`INSERT INTO bodies (hash, type, source, body, created_timestamp)
VALUES ($1, $2, $3, $4, $5)
ON CONFLICT (hash) DO NOTHING`, // 原子性忽略重复
hash, typ, source, bodyStr, createdTs,
)
if err != nil {
return err
}
return tx.Commit() // 仅成功时提交
}调用处替换原 bodyInsert.Exec(...)：
if _, ok := pr.BodiesHash[bodyHash]; !ok {
pr.BodiesHash[bodyHash] = true
if err := pr.insertBodyWithConflictHandling(
bodyHash, p.GetType(), p.GetSource(), p.GetBodyString(), nowUnix,
); err != nil {
// 注意：此处 err 可能是真正的约束冲突（非重试导致），或网络/SQL 错误
if pqErr, ok := err.(*pq.Error); ok && pqErr.Code == "23505" {
pr.Logger.Printf("Ignored duplicate hash (handled by ON CONFLICT): %s", bodyHash)
} else {
pr.Logger.Printf("Insert failed: %v | Body: %s | Hash: %s", err, bodyString, bodyHash)
}
}
}⚠️ 关键注意事项
- 禁用自动重试陷阱：在连接字符串中显式设置 connect_timeout=5 和 sslmode=disable（内网可信环境）或 sslmode=require（外网），避免 TLS 不稳定引发误重试；Go 1.4+ 虽支持 ALPN，但生产环境建议优先验证 SSL 配置稳定性。
- 内存去重 ≠ 数据库去重：BodiesHash 仅作性能优化（减少无效 SQL 调用），绝不能替代数据库层的唯一性保障。其生命周期需与业务语义对齐（如按批次清空）。
- 错误分类处理：ON CONFLICT DO NOTHING 返回的 pq.Error（SQLSTATE 23505）是预期行为，应静默忽略；其他错误（如 connection refused）需重试或告警。
- 性能权衡：ON CONFLICT 在高并发写入时比 SELECT ... FOR UPDATE 更高效，且避免锁表风险。
✅ 总结
解决该问题的核心逻辑是：放弃对 database/sql 自动重试机制的信任，将唯一性校验下沉至数据库原子操作层。通过 INSERT ... ON CONFLICT 替代应用层条件判断，配合显式事务控制，即可彻底消除因网络抖动、SSL 异常导致的“伪重复插入”。同时，合理配置连接参数与错误处理策略，确保系统在分布式环境下的确定性与可观测性。
