vault backup: 2026-04-28 20:56:51
This commit is contained in:
+157
-27
@@ -7,22 +7,34 @@ create time: 2026-04-28 00:00
|
||||
|
||||
## 概述
|
||||
|
||||
GORM **从不 panic**——所有错误都通过 `.Error` 字段返回。这种设计让业务层可以在不中断程序的情况下优雅地处理异常，但也意味着开发者需要养成「始终检查 Error」的习惯。
|
||||
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
|
||||
Result["db.XXX() → result"] --> HasErr{"result.Error != nil?"}
|
||||
HasErr --> |否| Success["继续业务逻辑 ✓"]
|
||||
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["记录日志 / 返回通用错误"]
|
||||
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
|
||||
```
|
||||
|
||||
## 核心错误常量
|
||||
@@ -37,7 +49,7 @@ 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
|
||||
}
|
||||
@@ -46,6 +58,9 @@ if errors.Is(result.Error, gorm.ErrRecordNotFound) {
|
||||
log.Printf("找到用户: %s", user.Name)
|
||||
```
|
||||
|
||||
> [!exemplar] 关键模式：先 `errors.Is` 精确判断，再兜底检查非空
|
||||
> 这段代码的精髓在于「**分层判断**」：第一层处理预期内的业务场景（找不到），第二层处理意外情况（连接断了）。如果反过来先检查 `nil`，会丢失对 `ErrRecordNotFound` 的精准处理能力。
|
||||
|
||||
> [!tip] 为什么用 errors.Is 而不是 ==？
|
||||
> `gorm.ErrRecordNotFound` 是一个 sentinal error（哨兵错误），Go 标准库的 `errors.Is()` 能正确处理包装过的错误链。直接用 `==` 在复杂场景中可能失效。
|
||||
|
||||
@@ -59,14 +74,16 @@ if errors.Is(result.Error, gorm.ErrDuplicatedKey) {
|
||||
return fmt.Errorf("该邮箱已被注册")
|
||||
}
|
||||
|
||||
// 外键约束失败
|
||||
// 外键约束失败：尝试创建一条指向不存在用户的订单
|
||||
type Order struct { UserID uint }
|
||||
result := db.Create(&Order{UserID: 999})
|
||||
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
|
||||
@@ -119,6 +136,7 @@ tx.Rollback() // ❌ 再回滚会报错！
|
||||
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)
|
||||
}
|
||||
@@ -128,6 +146,8 @@ func GetUserByID(db *gorm.DB, id uint) (*User, error) {
|
||||
}
|
||||
```
|
||||
|
||||
> [!exemplar] `%w` 是 Go 的错误包装语法 —— 它让外层错误仍然能被 `errors.Is()` 逐层识别。如果只写 `%v` ，上层的 `errors.Is(err, gorm.ErrRecordNotFound)` 将返回 false。
|
||||
|
||||
### 自定义错误处理器
|
||||
|
||||
```go
|
||||
@@ -165,26 +185,26 @@ func HandleCreateUser(c *gin.Context) {
|
||||
### ❌ 错误的写法
|
||||
|
||||
```go
|
||||
// 1. 完全忽略错误
|
||||
// 1. 完全忽略错误 —— 数据丢了你都不会知道
|
||||
db.Create(&user)
|
||||
|
||||
// 2. 只检查非 nil（会误判 ErrRecordNotFound）
|
||||
// 2. 只检查非 nil（会误把 ErrRecordNotFound 当成故障）
|
||||
if err := db.First(&user, 1).Error; err != nil {
|
||||
// ErrRecordNotFound 也会被当成一般错误处理
|
||||
// ErrRecordNotFound 也会被当成一般错误，导致用户看到 500 而不是 404
|
||||
log.Printf("error: %v", err)
|
||||
}
|
||||
|
||||
// 3. 先判断 Error != nil 再用 == 比较
|
||||
// 3. 先判断 Error != nil 再用 == 比较 —— 可能被 fmt.Errorf("%w") 包装后漏判
|
||||
err := db.First(&user, 1).Error
|
||||
if err != nil && err == gorm.ErrRecordNotFound {
|
||||
// 在某些情况下可能漏判
|
||||
// 在某些 GORM 版本或复杂场景中可能漏判
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ 正确的写法
|
||||
|
||||
```go
|
||||
// 模式一：errors.Is 优先
|
||||
// 模式一：errors.Is 优先（推荐日常使用）
|
||||
if err := db.First(&user, 1).Error; err != nil {
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
// 单独处理
|
||||
@@ -193,7 +213,7 @@ if err := db.First(&user, 1).Error; err != nil {
|
||||
}
|
||||
}
|
||||
|
||||
// 模式二：先赋值再判断
|
||||
// 模式二：switch + result.Error（适合多分支场景）
|
||||
result := db.First(&user, 1)
|
||||
switch {
|
||||
case errors.Is(result.Error, gorm.ErrRecordNotFound):
|
||||
@@ -204,7 +224,7 @@ 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")
|
||||
@@ -213,7 +233,12 @@ if result := db.First(&user, 1); result.Error != nil {
|
||||
}
|
||||
```
|
||||
|
||||
## 连接错误与超时处理
|
||||
> [!tip] 什么时候用模式二（switch）？
|
||||
> 当你的 handler 需要同时处理多种业务错误时，`switch-case` 比嵌套 `if-else` **更清晰、更易扩展**。每新增一种错误类型只需加一个 case，不会让代码块不断缩进。
|
||||
|
||||
## 连接错误与连接池管理
|
||||
|
||||
### PingContext 探测
|
||||
|
||||
```go
|
||||
// 检测数据库是否可达
|
||||
@@ -233,25 +258,79 @@ if err := sqlDB.PingContext(ctx); err != nil {
|
||||
```
|
||||
|
||||
> [!tip] 结合健康检查
|
||||
> 在生产环境中，应该定期执行 `PingContext` 作为 K8s liveness/readiness probe，确保服务知道数据库是否可用。
|
||||
> 在生产环境中，应该定期执行 `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[操作返回结果] --> CheckErr{"result.Error 非空?"}
|
||||
Start[db 操作返回结果] --> CheckErr{"result.Error<br/>非空?"}
|
||||
CheckErr --> |否| Success["操作成功"]
|
||||
CheckErr --> |是| FirstCheck{errors.Is...}
|
||||
CheckErr --> |是| FirstCheck{errors.Is...?}
|
||||
|
||||
FirstCheck --> |ErrRecordNotFound| Handler1["处理: 返回默认值/404"]
|
||||
FirstCheck --> |ErrDuplicatedKey| Handler2["处理: 提示重复"]
|
||||
FirstCheck --> |ErrForeignKeyConstraintViolated| Handler3["处理: 检查关联"]
|
||||
FirstCheck --> |ErrTransactionFinished| Handler4["处理: 代码缺陷修复"]
|
||||
FirstCheck --> |都不匹配| DefaultHandler["处理: 通用错误/500"]
|
||||
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:#EF4444,color:#fff
|
||||
style DefaultHandler fill:#F59E0B,color:#fff
|
||||
```
|
||||
|
||||
## 常见坑点速查
|
||||
@@ -263,6 +342,57 @@ flowchart TD
|
||||
| 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" 模式，避免二次提交。
|
||||
|
||||
## 关联笔记
|
||||
|
||||
|
||||
Reference in New Issue
Block a user