all-in-kingsoft/hhs/GORM/14-错误处理.md

---
tags: [GORM, Go, ORM, 错误处理, ErrRecordNotFound, ErrDuplicatedKey, TransactionFinished]
create time: 2026-04-28 00:00
---

# 错误处理

## 概述

GORM **从不 panic**——所有错误都通过 `result.Error` 字段返回。这种设计让业务层可以在不中断程序的情况下优雅地处理异常，但也意味着开发者需要养成「始终检查 Error」的习惯。

核心要点：

- **每个 GORM 方法返回 `*gorm.DB`**（链式调用），真正的结果在 `.Error` 字段里 —— 忘记检查 `.Error` 是新手最常见的坑。
- **哨兵错误用 `errors.Is` 判断**，不要用 `==` ，因为 GORM 内部会用 `%w` 包装错误。
- **数据库错误分三层**：应用层（RecordNotFound / DuplicateKey）、事务层（TransactionFinished）、基础设施层（连接断开 / SQL 错误）—— 每一层的处理策略不同。

> [!question] 思考：如果 `db.Create(&user).Error` 是 nil，是不是就代表数据一定写入了？
> 
> 不一定。如果当前事务处于回滚状态，或者事务最终 Rollback 了，创建操作虽然 "成功" 了但不会被持久化。**错误检查必须和事务生命周期配合考虑**。我们后面会详细讲。

```mermaid
flowchart TD
    Start[db.XXX() 操作] --> Result["返回 result"]
    Result --> HasErr{"result.Error<br/>!= nil?"}
    HasErr --> |否| Success["继续业务逻辑"]
    HasErr --> |是| CheckType{判断错误类型}
    
    CheckType --> |ErrRecordNotFound| NotFound["404 / 默认值"]
    CheckType --> |ErrDuplicatedKey| Duplicate["409 / 提示修改"]
    CheckType --> |TransactionFinished| TxErr["500 / 代码缺陷"]
    CheckType --> |其他 errors.Is| Generic["记录日志 / 通用错误"]
    
    style Start fill:#4FC08D,color:#fff
    style Success fill:#3B82F6,color:#fff
    style NotFound fill:#EF4444,color:#fff
    style Generic fill:#F59E0B,color:#fff
```

## 核心错误常量

### gorm.ErrRecordNotFound

```go
var user User
result := db.First(&user, 1)

if errors.Is(result.Error, gorm.ErrRecordNotFound) {
    // 记录不存在 —— 可以返回 404 或设置默认值
    return http.NotFound(w, r)
} else if result.Error != nil {
    // 真正的数据库错误（连接失败、SQL 语法问题等）
    log.Printf("查询用户失败: %v", result.Error)
    return err
}

// 成功分支
log.Printf("找到用户: %s", user.Name)
```

> [!exemplar] 关键模式：先 `errors.Is` 精确判断，再兜底检查非空
> 这段代码的精髓在于「**分层判断**」：第一层处理预期内的业务场景（找不到），第二层处理意外情况（连接断了）。如果反过来先检查 `nil`，会丢失对 `ErrRecordNotFound` 的精准处理能力。

> [!tip] 为什么用 errors.Is 而不是 ==？
> `gorm.ErrRecordNotFound` 是一个 sentinal error（哨兵错误），Go 标准库的 `errors.Is()` 能正确处理包装过的错误链。直接用 `==` 在复杂场景中可能失效。

### gorm.ErrDuplicatedKey / gorm.ErrForeignKeyConstraintViolated

```go
result := db.Create(&User{Email: "alice@example.com"})

if errors.Is(result.Error, gorm.ErrDuplicatedKey) {
    // 唯一约束冲突 —— 通常是 Email 已注册
    return fmt.Errorf("该邮箱已被注册")
}

// 外键约束失败：尝试创建一条指向不存在用户的订单
type Order struct { UserID uint }
result = db.Create(&Order{UserID: 999})
if errors.Is(result.Error, gorm.ErrForeignKeyConstraintViolated) {
    return fmt.Errorf("指定的用户不存在")
}
```

> [!tip] `ErrDuplicatedKey` 和 `ErrForeignKeyConstraintViolated` 都来自数据库引擎本身（如 MySQL 的 errno 1062 / 1452），GORM 只是把它们包装成了哨兵错误。因此判断顺序没有严格要求，但一般**先判主键冲突再判外键**。

### gorm.TransactionFinished

```go
tx := db.Begin()
tx.Commit() // 先提交
tx.Rollback() // ❌ 再回滚会报错！
// result.Error == gorm.ErrTransactionFinished
```

> [!warning] 常见触发场景
> 这个错误最常见于 `defer Rollback()` 模式——如果 Commit 成功了但 defer 仍会执行 Rollback：
> ```go
> func Example() error {
>     tx := db.Begin()
>     defer func() {
>         if r := recover(); r != nil {
>             tx.Rollback()
>             panic(r)
>         }
>     }()
>     
>     // ... 操作 ...
>     
>     if err := tx.Commit().Error; err != nil {
>         tx.Rollback()
>         return err
>     }
>     // 到达这里说明 Commit 成功 —— defer 不会进 panic 分支
>     return nil
> }
> ```

### 常用错误常量汇总

| 常量 | 含义 | 典型 HTTP 状态码 | 处理建议 |
|------|------|-----------------|---------|
| `gorm.ErrRecordNotFound` | 查询结果为空 | 404 | 返回友好提示或默认值 |
| `gorm.ErrDuplicatedKey` | 唯一约束冲突 | 409 | 提示用户修改输入 |
| `gorm.ErrForeignKeyConstraintViolated` | 外键约束失败 | 400 | 检查关联数据是否存在 |
| `gorm.ErrInvalidData` | 数据无效 | 400 | 校验输入后重试 |
| `gorm.ErrTransactionFinished` | 事务已提交/回滚 | 500 | 代码逻辑 BUG，修复代码 |
| `gorm.ErrUnsupportedDriver` | 不支持的驱动 | 配置错误 | 检查 dsn 和驱动导入 |
| `gorm.ErrInvalidTransaction` | 无效的事务操作 | 500 | 检查事务上下文是否正确 |

## 自定义错误判断

### 包装业务错误

```go
func GetUserByID(db *gorm.DB, id uint) (*User, error) {
    var user User
    if err := db.First(&user, id).Error; err != nil {
        // 保留原始哨兵错误，方便上层继续用 errors.Is 判断
        if errors.Is(err, gorm.ErrRecordNotFound) {
            return nil, fmt.Errorf("用户 ID=%d 不存在: %w", id, err)
        }
        return nil, fmt.Errorf("查询用户失败: %w", err)
    }
    return &user, nil
}
```

> [!exemplar] `%w` 是 Go 的错误包装语法 —— 它让外层错误仍然能被 `errors.Is()` 逐层识别。如果只写 `%v` ，上层的 `errors.Is(err, gorm.ErrRecordNotFound)` 将返回 false。

### 自定义错误处理器

```go
// 统一错误解析器，适合中间件或框架层使用
func ParseDBError(err error) (int, string) {
    switch {
    case errors.Is(err, gorm.ErrRecordNotFound):
        return http.StatusNotFound, "资源未找到"
    case errors.Is(err, gorm.ErrDuplicatedKey):
        return http.StatusConflict, "数据冲突，请检查输入"
    case errors.Is(err, gorm.ErrForeignKeyConstraintViolated):
        return http.StatusBadRequest, "关联数据无效"
    case errors.Is(err, gorm.ErrTransactionFinished):
        return http.StatusInternalServerError, "系统内部错误"
    default:
        log.Printf("未分类数据库错误: %v", err)
        return http.StatusInternalServerError, "数据库操作失败"
    }
}

// 在 Gin handler 中使用
func HandleCreateUser(c *gin.Context) {
    err := createUserService(c.Request)
    if err != nil {
        status, msg := ParseDBError(err)
        c.JSON(status, gin.H{"error": msg})
        return
    }
    c.JSON(201, gin.H{"message": "创建成功"})
}
```

## 错误检查的正确姿势

### ❌ 错误的写法

```go
// 1. 完全忽略错误 —— 数据丢了你都不会知道
db.Create(&user)

// 2. 只检查非 nil（会误把 ErrRecordNotFound 当成故障）
if err := db.First(&user, 1).Error; err != nil {
    // ErrRecordNotFound 也会被当成一般错误，导致用户看到 500 而不是 404
    log.Printf("error: %v", err)
}

// 3. 先判断 Error != nil 再用 == 比较 —— 可能被 fmt.Errorf("%w") 包装后漏判
err := db.First(&user, 1).Error
if err != nil && err == gorm.ErrRecordNotFound {
    // 在某些 GORM 版本或复杂场景中可能漏判
}
```

### ✅ 正确的写法

```go
// 模式一：errors.Is 优先（推荐日常使用）
if err := db.First(&user, 1).Error; err != nil {
    if errors.Is(err, gorm.ErrRecordNotFound) {
        // 单独处理
    } else {
        // 其他数据库错误
    }
}

// 模式二：switch + result.Error（适合多分支场景）
result := db.First(&user, 1)
switch {
case errors.Is(result.Error, gorm.ErrRecordNotFound):
    handleNotFound()
case result.Error != nil:
    handleError(result.Error)
default:
    handleSuccess(user)
}

// 模式三：简洁单路径（适合函数入口校验）
if result := db.First(&user, 1); result.Error != nil {
    if errors.Is(result.Error, gorm.ErrRecordNotFound) {
        return nil, fmt.Errorf("user not found")
    }
    return nil, fmt.Errorf("db error: %w", result.Error)
}
```

> [!tip] 什么时候用模式二（switch）？
> 当你的 handler 需要同时处理多种业务错误时，`switch-case` 比嵌套 `if-else` **更清晰、更易扩展**。每新增一种错误类型只需加一个 case，不会让代码块不断缩进。

## 连接错误与连接池管理

### PingContext 探测

```go
// 检测数据库是否可达
sqlDB, err := db.DB()
if err != nil {
    return err
}

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

if err := sqlDB.PingContext(ctx); err != nil {
    log.Printf("数据库连接异常: %v", err)
    // 可以尝试重连、切换从库等
    return fmt.Errorf("database unavailable")
}
```

> [!tip] 结合健康检查
> 在生产环境中，应该定期执行 `PingContext` 作为 K8s liveness/readiness probe，确保服务知道数据库是否可用。Gin 项目里可以注册一个 `/health` 路由，里面做这一步即可。

### 连接池脏连接问题（重要！）

即使 Ping 通过了，**从连接池借出的连接也可能已断开**——这被称为 "stale connection" 或 "dead connection"。典型场景：MySQL 的 `wait_timeout` 默认 8 小时，空闲连接被服务端主动关闭，但 Go 端连接池不知情。

GORM v2 内置了 stale connection replacer（v2.0.9+），会自动重试一次死连接。但你仍需合理配置连接池参数：

```go
sqlDB, _ := db.DB()

// 最大空闲连接数 —— 设太高会浪费资源
sqlDB.SetMaxIdleConns(10)

// 最大打开连接数 —— 包括正在使用的 + 空闲的
sqlDB.SetMaxOpenConns(100)

// 每个连接的存活时间 —— 必须小于 MySQL wait_timeout（默认 8h）
// 建议设为 5min 以避免服务端超时踢掉连接
sqlDB.SetConnMaxLifetime(5 * time.Minute)

// 每个连接的闲置时间 —— 超过此时间的连接会被回收
sqlDB.SetConnMaxIdleTime(5 * time.Minute)
```

> [!warning] `SetConnMaxLifetime` vs `SetConnMaxIdleTime`
> - `SetConnMaxLifetime`: 连接的总寿命，超过后新请求不会再用这个连接。**主要用来避免服务端侧的超时断开**。
> - `SetConnMaxIdleTime`: 连接闲置多久后被回收。主要用于控制空闲连接数量，节省资源。
>
> 两者都建议设置，且 IdleTime < Lifetime < 数据库 wait_timeout。

### SQL 层级错误码判断

有时你需要更细粒度地判断错误来源（比如区分 "表不存在" 和 "字段类型不匹配"）：

```go
// 引入 MySQL 驱动以获取底层错误类型
import "github.com/go-sql-driver/mysql"

// 细粒度错误码判断
result := db.Exec("ALTER TABLE users ADD COLUMN email VARCHAR(255)")
if mysqlErr, ok := result.Error.(*mysql.MySQLError); ok {
    switch mysqlErr.Number {
    case 1060: // Duplicate column name
        log.Println("列已存在，跳过")
    case 1146: // Table doesn't exist
        log.Println("表不存在，需要初始化")
    default:
        log.Printf("MySQL error %d: %v", mysqlErr.Number, mysqlErr.Message)
    }
}
```

> [!exemplar] 什么时候用 SQL 层错误码？
> 一般业务逻辑不需要用到这一步。通常只在以下场景需要：**数据库迁移脚本**（幂等执行）、**建表/建库的自动初始化逻辑**、或者你需要区分不同 MySQL 错误号来做差异化重试策略时。

## 错误处理决策流程图

```mermaid
flowchart TD
    Start[db 操作返回结果] --> CheckErr{"result.Error<br/>非空?"}
    CheckErr --> |否| Success["操作成功"]
    CheckErr --> |是| FirstCheck{errors.Is...?}
    
    FirstCheck --> |ErrRecordNotFound| Handler1["404 / 默认值"]
    FirstCheck --> |ErrDuplicatedKey| Handler2["409 / 提示重复"]
    FirstCheck --> |ErrForeignKeyConstraintViolated| Handler3["400 / 检查关联"]
    FirstCheck --> |ErrTransactionFinished| Handler4["500 / 代码缺陷"]
    FirstCheck --> |都不匹配| DefaultHandler["500 / 通用数据库错误"]
    
    style Start fill:#4FC08D,color:#fff
    style Success fill:#3B82F6,color:#fff
    style DefaultHandler fill:#F59E0B,color:#fff
```

## 常见坑点速查

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 忘记检查 `.Error` | 以为方法直接返回 error | 养成 `if err := xxx().Error; err != nil` 习惯 |
| 用 `==` 而非 `errors.Is` | 哨兵错误被 fmt.Errorf("%w") 包装后丢失 | 统一使用 `errors.Is(err, gorm.xxx)` |
| Commit 后再 Rollback | defer 无条件执行回滚 | 只在 panic 分支中 Rollback |
| 把所有错误当 RecordNotFound | 没做错误类型分层 | 先用 errors.Is 精确判断 |
| 数据库断开时没检测到 | 连接池复用旧连接 | PingContext 定期探测 + SetConnMaxLifetime |
| 空闲连接被 MySQL 回收 | wait_timeout 与 Go 连接池不匹配 | 设置 ConnMaxLifetime < MySQL wait_timeout |

## 实战：GORM Interceptor 统一错误处理

在 Gin 项目中，可以通过 GORM 的 [Interceptor](https://gorm.io/docs/advanced.html#Interceptor) 机制或自定义 Middleware 统一处理数据库错误，避免在每个 handler 里重复写错误解析逻辑。

```go
// DBErrorLogger 记录所有非 NotFound 的数据库错误
func DBErrorLogger(logger *log.Logger) db.Interceptor {
    return &interceptor{logger: logger}
}

type interceptor struct {
    logger *log.Logger
}

func (i *interceptor) Before(name string) db.Interceptor {
    return i
}

func (i *interceptor) After(name string, result gorm.ResultInfo) gorm.ResultInfo {
    // 注意: Interceptor 的 result.Error 已经是方法调用后的最终结果
    if result.Error != nil && !errors.Is(result.Error, gorm.ErrRecordNotFound) {
        i.logger.Printf("[DB Error] operation=%s error=%v", name, result.Error)
    }
    return result
}
```

```go
// 注册到全局配置
db, _ := gorm.Open(mysql.Open(dsn), &gorm.Config{
    Logger: customLogger,
})
_ = db.Use(DBErrorLogger(log.New(os.Stdout, "[GORM]", log.LstdFlags)))
```

> [!tip] Interceptor vs Handler 层错误处理
> - **Interceptor（全局）**：负责日志记录和监控告警 —— "出错了我要知道"
> - **Handler（业务层）**：负责业务语义转换 —— "这个错对用户意味着什么"
>
> 两者互补：Intercepter 让你不会错过任何异常，Handler 层决定怎么回复客户端。

## 最佳实践清单

1. **统一入口检查**：在 service 层入口处统一做 `err != nil` 检查，不要散落在业务逻辑中。
2. **保留哨兵错误**：使用 `%w` 包装错误，让上层可以继续用 `errors.Is` 判断。
3. **HTTP 状态码映射**：用 switch-case 把错误类型映射为 HTTP 状态码，参考 `ParseDBError` 函数模式。
4. **日志分级**：`ErrRecordNotFound` 等预期内错误记 `info` / `debug`，真正故障记 `error`。
5. **连接池参数**：务必设置 `ConnMaxLifetime` 和 `ConnMaxIdleTime`，避免脏连接引发随机报错。
6. **事务安全**：优先使用 "Commit 成功才 return nil + defer panic only rollback" 模式，避免二次提交。

## 关联笔记

- [[03-CRUD 操作]]
- [[08-事务管理]]
- [[16-日志与调试]]