常见问题与最佳实践

Salmon2026/1/15大约 6 分钟GORM最佳实践FAQ

常见问题与最佳实践

一、常见问题

1.1 记录未找到错误

// 问题：查询不到记录时返回错误
var user User
err := db.First(&user, 1).Error
if err != nil {
    // err == gorm.ErrRecordNotFound
}

// 解决：判断是否为 RecordNotFound
if errors.Is(err, gorm.ErrRecordNotFound) {
    // 记录不存在
} else if err != nil {
    // 其他错误
}

// 或使用 Take（不返回 ErrRecordNotFound）
db.Take(&user, 1)

1.2 零值不更新

// 问题：零值字段不会被更新
db.Model(&user).Updates(User{Age: 0}) // Age 不会更新

// 解决方案1：使用 Select
db.Model(&user).Select("Age").Updates(User{Age: 0})

// 解决方案2：使用 map
db.Model(&user).Updates(map[string]interface{}{"age": 0})

// 解决方案3：使用 UpdateColumn
db.Model(&user).UpdateColumn("age", 0)

1.3 软删除查询

// 问题：查询不到软删除的记录
db.Find(&users) // 不包含软删除记录

// 解决：使用 Unscoped
db.Unscoped().Find(&users) // 包含软删除记录

// 只查询软删除记录
db.Unscoped().Where("deleted_at IS NOT NULL").Find(&users)

1.4 关联未加载

// 问题：关联数据为空
var user User
db.First(&user, 1)
fmt.Println(user.Articles) // 空切片

// 解决：使用 Preload
db.Preload("Articles").First(&user, 1)

1.5 批量插入返回 ID

// 问题：批量插入后获取 ID
users := []User{{Name: "张三"}, {Name: "李四"}}
db.Create(&users)

// 解决：ID 会自动填充到结构体
for _, user := range users {
    fmt.Println(user.ID) // 已填充
}

1.6 表名问题

// 问题：表名不正确
type User struct {} // 默认表名：users（复数）

// 解决方案1：使用单数表名
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
    NamingStrategy: schema.NamingStrategy{
        SingularTable: true, // 使用单数表名
    },
})

// 解决方案2：自定义表名
func (User) TableName() string {
    return "my_users"
}

1.7 时区问题

// 问题：时间不正确
// 解决：DSN 中指定时区
dsn := "user:pass@tcp(127.0.0.1:3306)/db?charset=utf8mb4&parseTime=True&loc=Local"

// 或使用 UTC
dsn := "user:pass@tcp(127.0.0.1:3306)/db?charset=utf8mb4&parseTime=True&loc=UTC"

1.8 连接池耗尽

// 问题：连接池耗尽
// 原因：未正确关闭 Rows

// 错误示例
rows, _ := db.Model(&User{}).Rows()
for rows.Next() {
    // 处理
}
// 忘记关闭

// 正确示例
rows, _ := db.Model(&User{}).Rows()
defer rows.Close() // 确保关闭

for rows.Next() {
    var user User
    db.ScanRows(rows, &user)
}

二、最佳实践

2.1 项目结构

myapp/
├── main.go
├── config/
│   └── database.go          # 数据库配置
├── models/
│   ├── user.go              # 用户模型
│   ├── article.go           # 文章模型
│   └── base.go              # 基础模型
├── repository/
│   ├── user_repo.go         # 用户数据访问层
│   └── article_repo.go      # 文章数据访问层
├── service/
│   ├── user_service.go      # 用户业务逻辑
│   └── article_service.go   # 文章业务逻辑
└── api/
    ├── user_handler.go      # 用户 API
    └── article_handler.go   # 文章 API

2.2 基础模型

// models/base.go
package models

import (
    "gorm.io/gorm"
    "time"
)

type BaseModel struct {
    ID        uint           `gorm:"primaryKey" json:"id"`
    CreatedAt time.Time      `json:"created_at"`
    UpdatedAt time.Time      `json:"updated_at"`
    DeletedAt gorm.DeletedAt `gorm:"index" json:"-"`
}

// 其他模型继承
type User struct {
    BaseModel
    Name  string `json:"name"`
    Email string `json:"email"`
}

2.3 Repository 模式

// repository/user_repo.go
package repository

type UserRepository struct {
    db *gorm.DB
}

func NewUserRepository(db *gorm.DB) *UserRepository {
    return &UserRepository{db: db}
}

func (r *UserRepository) Create(user *User) error {
    return r.db.Create(user).Error
}

func (r *UserRepository) FindByID(id uint) (*User, error) {
    var user User
    err := r.db.First(&user, id).Error
    if errors.Is(err, gorm.ErrRecordNotFound) {
        return nil, nil
    }
    return &user, err
}

func (r *UserRepository) FindByEmail(email string) (*User, error) {
    var user User
    err := r.db.Where("email = ?", email).First(&user).Error
    if errors.Is(err, gorm.ErrRecordNotFound) {
        return nil, nil
    }
    return &user, err
}

func (r *UserRepository) Update(user *User) error {
    return r.db.Save(user).Error
}

func (r *UserRepository) Delete(id uint) error {
    return r.db.Delete(&User{}, id).Error
}

func (r *UserRepository) List(offset, limit int) ([]User, int64, error) {
    var users []User
    var total int64
    
    r.db.Model(&User{}).Count(&total)
    err := r.db.Offset(offset).Limit(limit).Find(&users).Error
    
    return users, total, err
}

2.4 Service 层

// service/user_service.go
package service

type UserService struct {
    repo *repository.UserRepository
}

func NewUserService(repo *repository.UserRepository) *UserService {
    return &UserService{repo: repo}
}

func (s *UserService) Register(username, email, password string) (*User, error) {
    // 检查邮箱是否存在
    existing, err := s.repo.FindByEmail(email)
    if err != nil {
        return nil, err
    }
    if existing != nil {
        return nil, errors.New("邮箱已被注册")
    }
    
    // 密码加密
    hashedPassword, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
    if err != nil {
        return nil, err
    }
    
    // 创建用户
    user := &User{
        Username: username,
        Email:    email,
        Password: string(hashedPassword),
    }
    
    if err := s.repo.Create(user); err != nil {
        return nil, err
    }
    
    return user, nil
}

func (s *UserService) GetUser(id uint) (*User, error) {
    return s.repo.FindByID(id)
}

func (s *UserService) UpdateProfile(id uint, updates map[string]interface{}) error {
    user, err := s.repo.FindByID(id)
    if err != nil {
        return err
    }
    if user == nil {
        return errors.New("用户不存在")
    }
    
    // 更新字段
    if name, ok := updates["name"]; ok {
        user.Name = name.(string)
    }
    
    return s.repo.Update(user)
}

2.5 错误处理

// 自定义错误
var (
    ErrUserNotFound     = errors.New("用户不存在")
    ErrEmailExists      = errors.New("邮箱已存在")
    ErrInvalidPassword  = errors.New("密码错误")
)

// 统一错误处理
func (s *UserService) GetUser(id uint) (*User, error) {
    user, err := s.repo.FindByID(id)
    if err != nil {
        return nil, fmt.Errorf("查询用户失败: %w", err)
    }
    if user == nil {
        return nil, ErrUserNotFound
    }
    return user, nil
}

2.6 事务封装

// 事务辅助函数
func (s *UserService) WithTransaction(fn func(*gorm.DB) error) error {
    return s.db.Transaction(fn)
}

// 使用
func (s *UserService) TransferPoints(fromID, toID uint, points int) error {
    return s.WithTransaction(func(tx *gorm.DB) error {
        // 扣除积分
        if err := tx.Model(&User{}).
            Where("id = ? AND points >= ?", fromID, points).
            Update("points", gorm.Expr("points - ?", points)).Error; err != nil {
            return err
        }
        
        // 增加积分
        if err := tx.Model(&User{}).
            Where("id = ?", toID).
            Update("points", gorm.Expr("points + ?", points)).Error; err != nil {
            return err
        }
        
        return nil
    })
}

2.7 配置管理

// config/database.go
package config

type DatabaseConfig struct {
    Host            string
    Port            int
    User            string
    Password        string
    DBName          string
    MaxIdleConns    int
    MaxOpenConns    int
    ConnMaxLifetime time.Duration
}

func InitDB(cfg DatabaseConfig) (*gorm.DB, error) {
    dsn := fmt.Sprintf("%s:%s@tcp(%s:%d)/%s?charset=utf8mb4&parseTime=True&loc=Local",
        cfg.User, cfg.Password, cfg.Host, cfg.Port, cfg.DBName)
    
    db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
        Logger: logger.Default.LogMode(logger.Info),
        NamingStrategy: schema.NamingStrategy{
            SingularTable: true,
        },
    })
    
    if err != nil {
        return nil, err
    }
    
    sqlDB, err := db.DB()
    if err != nil {
        return nil, err
    }
    
    sqlDB.SetMaxIdleConns(cfg.MaxIdleConns)
    sqlDB.SetMaxOpenConns(cfg.MaxOpenConns)
    sqlDB.SetConnMaxLifetime(cfg.ConnMaxLifetime)
    
    return db, nil
}

2.8 测试

// user_service_test.go
package service

import (
    "testing"
    "github.com/stretchr/testify/assert"
    "gorm.io/driver/sqlite"
    "gorm.io/gorm"
)

func setupTestDB(t *testing.T) *gorm.DB {
    db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
    assert.NoError(t, err)
    
    // 自动迁移
    db.AutoMigrate(&User{})
    
    return db
}

func TestUserService_Register(t *testing.T) {
    db := setupTestDB(t)
    repo := NewUserRepository(db)
    service := NewUserService(repo)
    
    // 测试注册
    user, err := service.Register("张三", "test@example.com", "password123")
    assert.NoError(t, err)
    assert.NotNil(t, user)
    assert.Equal(t, "张三", user.Username)
    
    // 测试重复注册
    _, err = service.Register("李四", "test@example.com", "password456")
    assert.Error(t, err)
}

2.9 日志记录

// 自定义 Logger
type CustomLogger struct {
    logger *log.Logger
}

func (l *CustomLogger) LogMode(level logger.LogLevel) logger.Interface {
    return l
}

func (l *CustomLogger) Info(ctx context.Context, msg string, data ...interface{}) {
    l.logger.Printf("[INFO] "+msg, data...)
}

func (l *CustomLogger) Warn(ctx context.Context, msg string, data ...interface{}) {
    l.logger.Printf("[WARN] "+msg, data...)
}

func (l *CustomLogger) Error(ctx context.Context, msg string, data ...interface{}) {
    l.logger.Printf("[ERROR] "+msg, data...)
}

func (l *CustomLogger) Trace(ctx context.Context, begin time.Time, fc func() (string, int64), err error) {
    elapsed := time.Since(begin)
    sql, rows := fc()
    
    if err != nil {
        l.logger.Printf("[ERROR] %s [%v] [rows:%d] %s", err, elapsed, rows, sql)
    } else if elapsed > 200*time.Millisecond {
        l.logger.Printf("[SLOW] [%v] [rows:%d] %s", elapsed, rows, sql)
    } else {
        l.logger.Printf("[TRACE] [%v] [rows:%d] %s", elapsed, rows, sql)
    }
}

2.10 迁移管理

// migrations/migrate.go
package migrations

func AutoMigrate(db *gorm.DB) error {
    return db.AutoMigrate(
        &User{},
        &Article{},
        &Comment{},
        &Tag{},
    )
}

// 手动迁移
func Migrate(db *gorm.DB) error {
    // 创建表
    if err := db.Migrator().CreateTable(&User{}); err != nil {
        return err
    }
    
    // 添加字段
    if !db.Migrator().HasColumn(&User{}, "nickname") {
        if err := db.Migrator().AddColumn(&User{}, "nickname"); err != nil {
            return err
        }
    }
    
    // 添加索引
    if !db.Migrator().HasIndex(&User{}, "idx_email") {
        if err := db.Migrator().CreateIndex(&User{}, "Email"); err != nil {
            return err
        }
    }
    
    return nil
}

三、性能建议

3.1 查询优化清单

✅ 只查询需要的字段
✅ 使用索引字段查询
✅ 避免 N+1 查询
✅ 使用批量操作
✅ 合理使用预加载
✅ 分页查询大数据集
✅ 使用连接池
✅ 启用预编译

3.2 安全建议

✅ 使用参数化查询防止 SQL 注入
✅ 密码加密存储
✅ 敏感字段不序列化
✅ 使用事务保证数据一致性
✅ 定期备份数据库