272 lines
8.3 KiB
Markdown
272 lines
8.3 KiB
Markdown
---
|
||
tags: [GORM, Go, ORM, 错误处理, ErrRecordNotFound, ErrDuplicatedKey, TransactionFinished]
|
||
create time: 2026-04-28 00:00
|
||
---
|
||
|
||
# 错误处理
|
||
|
||
## 概述
|
||
|
||
GORM **从不 panic**——所有错误都通过 `.Error` 字段返回。这种设计让业务层可以在不中断程序的情况下优雅地处理异常，但也意味着开发者需要养成「始终检查 Error」的习惯。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Result["db.XXX() → result"] --> HasErr{"result.Error != 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
|
||
```
|
||
|
||
## 核心错误常量
|
||
|
||
### 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 {
|
||
// 真正的数据库错误
|
||
log.Printf("查询用户失败: %v", result.Error)
|
||
return err
|
||
}
|
||
|
||
// 成功分支
|
||
log.Printf("找到用户: %s", user.Name)
|
||
```
|
||
|
||
> [!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("指定的用户不存在")
|
||
}
|
||
```
|
||
|
||
### 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 {
|
||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||
return nil, fmt.Errorf("用户 ID=%d 不存在: %w", id, err)
|
||
}
|
||
return nil, fmt.Errorf("查询用户失败: %w", err)
|
||
}
|
||
return &user, nil
|
||
}
|
||
```
|
||
|
||
### 自定义错误处理器
|
||
|
||
```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 也会被当成一般错误处理
|
||
log.Printf("error: %v", err)
|
||
}
|
||
|
||
// 3. 先判断 Error != nil 再用 == 比较
|
||
err := db.First(&user, 1).Error
|
||
if err != nil && err == gorm.ErrRecordNotFound {
|
||
// 在某些情况下可能漏判
|
||
}
|
||
```
|
||
|
||
### ✅ 正确的写法
|
||
|
||
```go
|
||
// 模式一：errors.Is 优先
|
||
if err := db.First(&user, 1).Error; err != nil {
|
||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||
// 单独处理
|
||
} else {
|
||
// 其他数据库错误
|
||
}
|
||
}
|
||
|
||
// 模式二：先赋值再判断
|
||
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)
|
||
}
|
||
```
|
||
|
||
## 连接错误与超时处理
|
||
|
||
```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，确保服务知道数据库是否可用。
|
||
|
||
## 错误处理决策流程图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start[操作返回结果] --> CheckErr{"result.Error 非空?"}
|
||
CheckErr --> |否| Success["操作成功"]
|
||
CheckErr --> |是| FirstCheck{errors.Is...}
|
||
|
||
FirstCheck --> |ErrRecordNotFound| Handler1["处理: 返回默认值/404"]
|
||
FirstCheck --> |ErrDuplicatedKey| Handler2["处理: 提示重复"]
|
||
FirstCheck --> |ErrForeignKeyConstraintViolated| Handler3["处理: 检查关联"]
|
||
FirstCheck --> |ErrTransactionFinished| Handler4["处理: 代码缺陷修复"]
|
||
FirstCheck --> |都不匹配| DefaultHandler["处理: 通用错误/500"]
|
||
|
||
style Start fill:#4FC08D,color:#fff
|
||
style Success fill:#3B82F6,color:#fff
|
||
style DefaultHandler fill:#EF4444,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 |
|
||
|
||
## 关联笔记
|
||
|
||
- [[03-CRUD 操作]]
|
||
- [[08-事务管理]]
|
||
- [[16-日志与调试]]
|