Go 源码之 gorm 框架

// DB 是 GORM 数据库操作的核心结构体
type DB struct {
    // 数据库连接池（不同数据库有不同实现，如 MySQL 的 sql.DB）
    connPool ConnPool
    // 数据库适配器（适配 MySQL、PostgreSQL 等不同数据库）
    dialector Dialector
    // 配置信息（如是否开启日志、超时时间、命名策略等）
    config *Config
    // 回调函数集合（如 BeforeCreate、AfterQuery 等生命周期钩子）
    callbacks *Callbacks
    // 当前 SQL 构建的上下文信息（包含模型、条件、SQL 语句等）
    statement *Statement
    // 错误信息（存储当前操作的错误）
    error error
    // 日志器（记录 SQL 执行、错误等日志）
    logger logger.Interface
}

// Open 是初始化 DB 实例的入口方法
func Open(dialector Dialector, opts ...Option) (*DB, error) {
    // 1. 初始化配置（合并默认配置和用户传入配置）
    cfg := &Config{}
    for _, opt := range opts {
        opt(cfg)
    }
    // 2. 初始化日志器（默认使用默认日志器）
    if cfg.Logger == nil {
        cfg.Logger = logger.Default
    }
    // 3. 创建 DB 实例
    db := &DB{
        dialector: dialector,
        config:    cfg,
        logger:    cfg.Logger,
        callbacks: &Callbacks{},
    }
    // 4. 初始化数据库连接池（通过适配器建立连接）
    if err := db.initializeConnPool(); err != nil {
        return nil, err
    }
    // 5. 初始化回调函数（注册默认的生命周期钩子）
    db.callbacks.Initialize(db)
    return db, nil
}

// 初始化数据库连接池
func (db *DB) initializeConnPool() error {
    // 通过适配器的 Connect 方法建立连接，获取连接池
    connPool, err := db.dialector.Connect(db)
    if err != nil {
        return err
    }
    db.connPool = connPool
    return nil
}

// Schema 存储模型与数据库表的映射信息
type Schema struct {
    // 模型对应的结构体类型（如 *User）
    Type reflect.Type
    // 表名（默认是结构体名复数形式，可通过标签自定义）
    Table string
    // 主键字段信息
    PrimaryFields []*Field
    // 所有字段的映射信息（key 是字段名，value 是字段详情）
    Fields map[string]*Field
    // 字段名到数据库列名的映射（处理命名策略，如蛇形命名）
    Columns map[string]string
    // 数据库列名到字段名的反向映射
    ColumnFields map[string]*Field
    // 模型的关联信息（如 HasOne、BelongsTo 等）
    Relationships map[string]*Relationship
}

// Field 存储结构体字段与数据库列的映射信息
type Field struct {
    // 结构体字段名（如 ID、Name）
    Name string
    // 数据库列名（如 id、user_name，受命名策略影响）
    Column string
    // 字段类型（如 int、string）
    Type reflect.Type
    // 主键标识
    PrimaryKey bool
    // 自增标识
    AutoIncrement bool
    // 非空标识
    NotNull bool
    // 字段标签信息（如 gorm:"size:255"）
    Tag Settings
    // 字段的值（运行时存储字段的具体值）
    Value reflect.Value
}

// Parse 是解析模型为 Schema 的核心方法
func Parse(dialector Dialector, model interface{}, opts ...SchemaOption) (*Schema, error) {
    // 1. 获取模型的反射类型（支持指针或值类型）
    typ := reflect.Indirect(reflect.ValueOf(model)).Type()
    schema := &Schema{
        Type:          typ,
        Fields:        make(map[string]*Field),
        Columns:       make(map[string]string),
        ColumnFields:  make(map[string]*Field),
        Relationships: make(map[string]*Relationship),
    }
    // 2. 应用配置（如自定义表名、命名策略）
    for _, opt := range opts {
        opt(schema)
    }
    // 3. 解析表名（默认使用命名策略，如 User → users）
    if schema.Table == "" {
        schema.Table = dialector.NamingStrategy().TableName(typ.Name())
    }
    // 4. 解析结构体字段，生成 Field 信息
    for i := 0; i < typ.NumField(); i++ {
        structField := typ.Field(i)
        // 跳过未导出字段（首字母小写）
        if structField.PkgPath != "" {
            continue
        }
        // 解析字段标签和属性，生成 Field 实例
        field, err := parseField(dialector, schema, structField)
        if err != nil {
            return nil, err
        }
        schema.Fields[field.Name] = field
        schema.Columns[field.Name] = field.Column
        schema.ColumnFields[field.Column] = field
        // 标记主键字段
        if field.PrimaryKey {
            schema.PrimaryFields = append(schema.PrimaryFields, field)
        }
    }
    // 5. 解析模型关联关系（如 HasMany）
    if err := schema.parseRelationships(dialector); err != nil {
        return nil, err
    }
    return schema, nil
}

// Statement 存储 SQL 构建和执行的上下文信息
type Statement struct {
    // 关联的 DB 实例
    DB *DB
    // 模型的 Schema 信息
    Schema *Schema
    // 当前操作的模型实例（如 &User{}）
    Model interface{}
    // SQL 语句（如 SELECT * FROM users WHERE id = ?）
    SQL string
    // SQL 绑定参数（如 [1]，替换 SQL 中的 ?）
    Vars []interface{}
    // 当前操作类型（如 Create、Query、Update、Delete）
    Op Op
    // 查询条件（存储 Where、Having 等条件）
    Conditions []Condition
    // 选择的字段（如 SELECT id, name FROM ...）
    Selects []string
    // 排除的字段（如 SELECT * EXCEPT password FROM ...）
    Omits []string
    // 排序条件（如 ORDER BY id DESC）
    Orders []OrderBy
    // 分页信息（如 LIMIT 10 OFFSET 20）
    Limit, Offset int
    // 关联查询信息
    Relationships []*Relationship
}

// Build 是构建 SQL 语句的核心方法
func (stmt *Statement) Build(clauses ...Clause) error {
    // 1. 初始化 Schema（若未设置，从 Model 解析）
    if stmt.Schema == nil && stmt.Model != nil {
        schema, err := Parse(stmt.DB.dialector, stmt.Model)
        if err != nil {
            return err
        }
        stmt.Schema = schema
    }
    // 2. 应用默认子句（根据操作类型，如 Query 对应 SELECT 子句）
    defaultClauses := getDefaultClauses(stmt.Op)
    clauses = append(defaultClauses, clauses...)
    // 3. 遍历子句，构建 SQL 片段
    for _, clause := range clauses {
        if err := clause.Build(stmt); err != nil {
            return err
        }
    }
    // 4. 处理 SQL 美化（如添加空格、换行，仅开发环境）
    if stmt.DB.config.PrepareStmt || stmt.DB.config.DisableAutomaticPing {
        stmt.SQL = stmt.DB.dialector.Quote(stmt.SQL)
    }
    return nil
}

// 以 Where 条件为例，构建查询条件子句
func (c Condition) Build(stmt *Statement) error {
    // 1. 解析条件（支持 map、struct、字符串等多种形式）
    expr, vars, err := c.Expr.Build(stmt)
    if err != nil {
        return err
    }
    // 2. 将条件添加到 SQL 中（如 WHERE id = ?）
    if stmt.SQL == "" {
        stmt.SQL = fmt.Sprintf("WHERE %s", expr)
    } else {
        stmt.SQL = fmt.Sprintf("%s AND %s", stmt.SQL, expr)
    }
    // 3. 添加绑定参数
    stmt.Vars = append(stmt.Vars, vars...)
    return nil
}

// Dialector 数据库适配器接口，定义数据库相关的核心能力
type Dialector interface {
    // 建立数据库连接，返回连接池
    Connect(*DB) (ConnPool, error)
    // 获取数据库名称（如 mysql、postgres）
    Name() string
    // 命名策略（表名、列名的命名规则，如蛇形命名）
    NamingStrategy() schema.Namer
    // 构建 SQL 子句（如 LIMIT、OFFSET 在不同数据库的差异）
    BuildClause(clause Clause, stmt *Statement) error
    // 处理数据类型映射（如 Go 的 time.Time 对应数据库的 DATETIME）
    DataTypeOf(field *schema.Field) string
    // 检查错误类型（如判断是否为唯一键冲突错误）
    TranslateError(err error) error
}

// 以 MySQL 适配器为例，实现 Dialector 接口
type MySQL struct {
    // MySQL 连接字符串（如 root:123456@tcp(127.0.0.1:3306)/test?charset=utf8mb4）
    DSN string
    // 命名策略（默认蛇形命名）
    Namer schema.Namer
    // 其他配置（如超时时间、是否开启预处理）
    Config Config
}

// Connect 实现 Dialector 接口，建立 MySQL 连接
func (m MySQL) Connect(db *DB) (ConnPool, error) {
    // 1. 调用标准库 sql.Open 建立连接
    sqlDB, err := sql.Open("mysql", m.DSN)
    if err != nil {
        return nil, err
    }
    // 2. 应用配置（如设置连接池大小、超时时间）
    if err := sqlDB.Ping(); err != nil {
        return nil, err
    }
    sqlDB.SetMaxOpenConns(m.Config.MaxOpenConns)
    sqlDB.SetMaxIdleConns(m.Config.MaxIdleConns)
    sqlDB.SetConnMaxLifetime(m.Config.ConnMaxLifetime)
    return sqlDB, nil
}

// DataTypeOf 实现 Dialector 接口，映射 Go 类型到 MySQL 类型
func (m MySQL) DataTypeOf(field *schema.Field) string {
    switch field.Type.Kind() {
    case reflect.Int, reflect.Int64:
        if field.AutoIncrement {
            return "int AUTO_INCREMENT"
        }
        return "int"
    case reflect.String:
        if size, ok := field.Tag.Get("size"); ok {
            return fmt.Sprintf("varchar(%s)", size)
        }
        return "varchar(255)"
    case reflect.Bool:
        return "tinyint(1)"
    case reflect.Struct:
        if field.Type == reflect.TypeOf(time.Time{}) {
            return "datetime"
        }
    }
    return ""
}

// Config GORM config
type Config struct {
    // GORM perform single create, update, delete operations in transactions by default to ensure database data integrity.You can disable it by setting `SkipDefaultTransaction` to true
  // 为了确保数据一致性，GORM 会在事务里执行写入操作（创建、更新、删除）。如果没有这方面的要求，您可以在初始化时禁用它。
    // 系统的默认事务：我们的gorm连接到数据库后，我们所做的增删改查操作，只要是这种链式的，gorm会自动的帮我们以事务的方式给串联起来，保证数据的一致性
    SkipDefaultTransaction bool

    // NamingStrategy tables, columns naming strategy
  // 表名命名策略，在使用AutoMigter时，会将model的名转小写并+s，SingularTable: true, // love表将是love，不再是loves，即可成功取消表明被加s，或者在model结构实现TableName()方法即可自定义表名
    NamingStrategy schema.Namer

    // FullSaveAssociations full save associations
  // 在创建、更新记录时，GORM 会通过 Upsert 自动保存关联及其引用记录
    FullSaveAssociations bool

    // Logger 支持自定义logger实现
    Logger logger.Interface

    // NowFunc the function to be used when creating a new timestamp
  // 更改创建时间使用的函数
    NowFunc func() time.Time

    // DryRun generate sql without execute
  // 生成 SQL 但不执行，可以用于准备或测试生成的 SQL，参考 会话 获取详情
    DryRun bool

    // PrepareStmt executes the given query in cached statement
  // PreparedStmt 在执行任何 SQL 时都会创建一个 prepared statement 并将其缓存，以提高后续的效率，参考 会话 获取详情
    PrepareStmt bool

    // DisableAutomaticPing
  // 在完成初始化后，GORM 会自动 ping 数据库以检查数据库的可用性，若要禁用该特性，可将其设置为 true
    DisableAutomaticPing bool

    // DisableForeignKeyConstraintWhenMigrating
    DisableForeignKeyConstraintWhenMigrating bool

    // DisableNestedTransaction disable nested transaction
  // 禁用嵌套事务；GORM 会使用 SavePoint(savedPointName)，RollbackTo(savedPointName) 为你提供嵌套事务支持
    DisableNestedTransaction bool

    // AllowGlobalUpdate allow global update
    AllowGlobalUpdate bool

    // QueryFields executes the SQL query with all fields of the table
  // 默认select * from，QueryFields=true的情况下，
    QueryFields bool

    // CreateBatchSize default create batch size
  // 设置批量创建的最大数
    CreateBatchSize int

    // ClauseBuilders clause builder
    ClauseBuilders map[string]clause.ClauseBuilder

    // ConnPool db conn pool
    ConnPool ConnPool

    // Dialector database dialector
    Dialector

    // Plugins registered plugins
    Plugins map[string]Plugin

  // 回调函数，又称钩子函数
    callbacks  *callbacks
    cacheStore *sync.Map
}