Gorm返回PostgreSQL重复键错误无法转为*pq.Error问题排查

问题核心 #

你遇到的问题是PostgreSQL返回的唯一键违规错误（SQLSTATE 23505）被Gorm多层包装，直接用*pq.Error或*pgconn.PgError类型断言无法命中，导致无法触发自定义的重复键错误逻辑。

解决方案 #

1. 更新依赖包导入 #

如果你的项目使用的是新版PostgreSQL驱动（pgx/v5），替换旧的pq包为pgconn：

import (
    "errors"

    "github.com/jackc/pgx/v5/pgconn" // 替代原github.com/lib/pq
    "github.com/sirupsen/logrus"
    "gorm.io/gorm"
)

2. 修改错误解析函数 #

使用errors.As递归穿透Gorm的错误包装，找到底层的PostgreSQL错误：

var (
    // ErrRecordNotFound indicates that specified record was not found.
    ErrRecordNotFound = errors.New("record not found")
    // ErrDuplicateEntry indicates that duplicate entry for this key exists.
    ErrDuplicateEntry = errors.New("record already exists")
)

// ParseError tries to catch gorm or sql driver error and return
// wrapped appropriate model error.
func ParseError(err error) error {
    switch {
    case err == nil:
        return nil
    case errors.Is(err, gorm.ErrRecordNotFound):
        return ErrRecordNotFound
    case errors.Is(err, gorm.ErrDuplicatedKey):
        return ErrDuplicateEntry
    default:
        // 递归查找底层的PgError
        var pgErr *pgconn.PgError
        if errors.As(err, &pgErr) && pgErr.Code == "23505" {
            logrus.Error("捕获到PostgreSQL唯一键违规错误")
            logrus.Errorf("约束名: %s", pgErr.ConstraintName)
            logrus.Errorf("错误详情: %v", pgErr)
            return ErrDuplicateEntry
        }

        logrus.Errorf("未处理的错误: %v", err)
        logrus.Errorf("错误信息: %s", err.Error())
        return err
    }
}

关键说明 #

• 用errors.As替代直接断言：Gorm会将驱动错误包装为自身的错误类型，errors.As会遍历整个错误链，找到匹配的底层错误类型，而直接类型断言只能获取最外层错误。
• 直接使用SQLSTATE码：用23505（唯一键违规的标准SQLSTATE码）判断比Code.Name()更稳定，避免驱动版本差异导致的名称变化。
• 验证错误链：如果仍无法捕获，可添加以下函数打印错误链，确认底层错误类型：

func printErrorChain(err error) {
    for err != nil {
        logrus.Errorf("错误类型: %T, 内容: %v", err, err)
        err = errors.Unwrap(err)
    }
}

在ParseError的default分支调用该函数，即可看到错误被包装的层级和各层类型。

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