本文详解如何在 go 应用中捕获、分类并人性化处理 postgresql 的 sql 约束错误（如 unique、foreign key、not null），借助 `lib/pq` 的标准错误结构，将底层数据库错误转化为前端可理解的 http 响应。
在 Go 与 PostgreSQL 协同开发中，直接向客户端暴露原始数据库错误（如 pq: duplicate key value violates unique constraint "users_email_key"）既不安全也不友好。理想做法是：识别错误类型 → 映射语义化提示 → 返回恰当 HTTP 状态码。这依赖于 PostgreSQL 标准化定义的五位 SQLSTATE 错误码（如 "23505" 表示唯一约束冲突），而 github.com/lib/pq 驱动已将其封装为结构化 *pq.Error 类型，包含 Code、Message、Detail、Hint 等关键字段。
以下是一个生产就绪的错误处理器示例，兼顾可读性、安全性与扩展性：
import (
"database/sql"
"fmt"
"net/http"
"strconv"
"github.com/lib/pq"
)
// ShowError 将底层错误转换为用户友好的 HTTP 响应
func ShowError(w http.ResponseWriter, r *http.Request, err error) {
switch e := err.(type) {
case *pq.Error:
switch e.Code {
case "23502": // not-null violation
http.Error(w,
fmt.Sprintf("缺少必要信息：%s", e.Message),
http.StatusBadRequest)
return
case "23503": // foreign key violation
if r.Method == "DELETE" {
http.Error(w,
fmt.Sprintf("该记录被其他数据引用，无法删除：%s",
e.Detail),
http.StatusForbidden)
return
}
http.Error(w,
fmt.Sprintf("关联数据无效：%s", e.Message),
http.StatusBadRequest)
return
case "23505": // unique violation
http.Error(w,
fmt.Sprintf("该值已存在，请检查重复项：%s",
e.Detail),
http.StatusConflict) // 使用 409 更符合 REST 语义
return
case "23514": // check constraint violation
http.Error(w,
fmt.Sprintf("输入数据不符合业务规则：%s", e.Message),
http.StatusBadRequest)
return
default:
// 未明确处理的数据库错误，保留 Detail/Hint 辅助调试，但屏蔽敏感信息
msg := e.Message
if e.Detail != "" {
msg += "\n详情：" + e.Detail
}
if e.Hint != "" {
msg += "\n建议：" + e.Hint
}
http.Error(w, msg, http.StatusInternalServerError)
return
}
case *strconv.NumError: // 类型转换失败（如字符串转 int）
http.Error(w,
fmt.Sprintf("参数格式错误：\"%s\" 不是有效数字", e.Num),
http.StatusBadRequest)
return
case sql.ErrNoRows: // 查询无结果
http.NotFound(w, r)
return
default:
// 其他未知错误（如连接超时、驱动 panic）
http.Error(w, "服务暂时不可用", http.StatusInternalServerError)
return
}
}关键实践说明：
- ✅ 优先使用 SQLSTATE 码而非错误文本：PostgreSQL 的五位码（如 "23505"）稳定、国际化、不受 locale 影响；而 e.Message 可能含敏感表名/字段名，需谨慎暴露。
- ✅ HTTP 状态码语义化：
- 400 Bad Request：用于 NOT NULL、CHECK 等客户端输入校验失败；
- 409 Conflict：更精准表达 UNIQUE 冲突（比 403 Forbidden 更符合 RFC 7231）；
- 403 Forbidden：仅适用于权限或策略性拒绝（如外键级联限制）；
- 404 Not Found：配合 sql.ErrNoRows 处理不存在资源。
- ⚠️ 安全注意事项：
- 生产环境禁用 e.Detail 和 e.Hint 的直接透出（示例中已做条件控制），避免泄露数据库结构；
- 对 e.Message 做白名单过滤或重写，防止 SQL 注入式错误消息。
- ? 可扩展建议：
- 将错误码映射提取为常量或配置表（如 ErrCodeUnique = "23505"），便于维护；
- 结合 i18n 包（如 golang.org/x/text/language）实现多语言错误提示；
- 在日志中完整记录原始 *pq.Error（含 Severity, Position），供运维排查。
通过此模式，开发者能将数据库约束错误转化为清晰、可控、安全的 API 响应，显著提升系统健壮性与用户体验。
