二、元数据、SQL 编程与结果集处理

package main

import (
    "fmt"
    "reflect"
)

// User 测试模型
type User struct {
    Id   int64
    Name string
    // 私有字段：反射能拿到类型信息，但拿不到值
    email string
}

func main() {
    u := User{Id: 1, Name: "大明", email: "daming@example.com"}

    // reflect.TypeOf 获取类型信息
    typ := reflect.TypeOf(u)
    // reflect.ValueOf 获取值信息
    val := reflect.ValueOf(u)

    // 只有 Kind == Struct 的才有字段
    // 指针类型是没有字段的！
    if typ.Kind() != reflect.Struct {
        fmt.Println("不是结构体")
        return
    }

    // 遍历所有字段
    for i := 0; i < typ.NumField(); i++ {
        field := typ.Field(i)
        fieldVal := val.Field(i)
        fmt.Printf("字段名: %s, 类型: %s, 值: %v\n",
            field.Name, field.Type, fieldVal)
    }
    // 输出：
    // 字段名: Id, 类型: int64, 值: 1
    // 字段名: Name, 类型: string, 值: 大明
    // 字段名: email, 类型: string, 值: daming@example.com
}

// registry.go 文件

import (
    "reflect"
    "sync"
)

// registry 是元数据注册中心
// 负责解析模型、缓存元数据
type registry struct {
    // mu 保护 models 的并发访问
    mu sync.RWMutex
    // models 存储已解析的模型元数据
    // key 是 reflect.Type（唯一确定一个类型）
    // 为什么用 reflect.Type？
    //   - 类型名：不同包可能有同名结构体（buyer.User vs seller.User）
    //   - 表名：在拿到元数据之前，不知道表名是什么
    //   - reflect.Type：唯一确定一个类型
    models map[reflect.Type]*Model
}

// Model 代表一个模型的元数据
type Model struct {
    TableName string
    FieldMap  map[string]*Field
}

// Field 代表一个字段的元数据
type Field struct {
    ColName string         // 数据库列名
    Type    reflect.Type   // Go 类型
    Offset  uintptr        // 字段偏移量（用于 unsafe 结果集处理）
}

// get 获取模型的元数据（带缓存，带并发安全）
// 使用 Double-Check 读写锁模式
func (r *registry) get(val any) (*Model, error) {
    typ := reflect.TypeOf(val)
    // 处理指针类型：*User -> User
    for typ.Kind() == reflect.Ptr {
        typ = typ.Elem()
    }

    // 第一次查找：读锁（大部分情况下模型已解析过）
    r.mu.RLock()
    m, ok := r.models[typ]
    r.mu.RUnlock()
    if ok {
        return m, nil
    }

    // 缓存未命中，需要写锁来解析和写入
    r.mu.Lock()
    defer r.mu.Unlock()

    // Double-Check：可能在等锁期间，别的 goroutine 已经解析好了
    m, ok = r.models[typ]
    if ok {
        return m, nil
    }

    // 确实没有，开始解析
    m, err := r.parseModel(val)
    if err != nil {
        return nil, err
    }
    r.models[typ] = m
    return m, nil
}

// 方式一：标签自定义列名
type User struct {
    // orm 标签：column=user_name 表示列名是 user_name
    Name string `orm:"column=user_name"`
    Age  int
}

// 方式二：接口自定义表名
// Go 的标签只能声明在字段上，不能声明在类型上
// 所以表级别的定制需要用接口
type TableName interface {
    TableName() string
}

// User 实现了 TableName 接口
type User struct {
    Id   int64
    Name string
}

// 自定义表名为 user_t
func (u User) TableName() string {
    return "user_t"
}

// 方式三：编程注册（Option 模式）
// 用法：db.Register(&User{}, orm.WithTableName("user_t"))
func WithTableName(name string) ModelOption {
    return func(m *Model) error {
        m.TableName = name
        return nil
    }
}

package main

import (
    "database/sql"
    "fmt"
    // 匿名引入 driver 包
    // 常见错误：忘记匿名引入 driver 包！
    // 如果不引入，sql.Open 找不到对应的驱动，会报错
    _ "github.com/go-sql-driver/mysql"
    _ "github.com/mattn/go-sqlite3"
)

func main() {
    // ========== 方式一：sql.Open ==========
    // Open 不会立即建立连接，而是延迟到第一次查询时才真正连接
    // 参数1: driver —— 驱动的名字，例如 "mysql"、"sqlite3"
    // 参数2: dsn —— 数据库连接信息（Data Source Name）
    // MySQL DSN 格式：用户名:密码@tcp(主机:端口)/数据库名?参数
    db, err := sql.Open("mysql", "root:password@tcp(127.0.0.1:3306)/test_db")
    if err != nil {
        panic(err)
    }
    defer db.Close()

    // 验证连接是否可用（Open 不会真正连接，Ping 才会）
    err = db.Ping()
    if err != nil {
        panic(err)
    }
    fmt.Println("数据库连接成功")

    // ========== 方式二：sql.OpenDB ==========
    // OpenDB 接收一个 driver.Connector 参数
    // 一般用于接入自定义驱动，例如将分库分表做成一个驱动
    // 也常用于测试（配合 sqlmock）
    //
    // db2, err := sql.OpenDB(customConnector)
}

// ========== 插入数据 ==========
// 使用 Exec 执行 INSERT 语句
// 返回 sql.Result 和 error
result, err := db.Exec(
    "INSERT INTO user(name, age) VALUES(?, ?)",
    "大明", 28, // 参数用 ? 占位，不要拼接进 SQL（防止 SQL 注入）
)
if err != nil {
    return err
}
// sql.Result 提供两个方法：
// LastInsertId() —— 获取自增 ID
// RowsAffected() —— 获取影响的行数
id, _ := result.LastInsertId()
fmt.Printf("插入成功，ID = %d\n", id)

// ========== 使用 ExecContext 控制超时 ==========
// ExecContext 可以传入 context 来控制超时
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
result, err = db.ExecContext(ctx,
    "UPDATE user SET age = ? WHERE id = ?",
    29, 1,
)
if err != nil {
    return err
}
affected, _ := result.RowsAffected()
fmt.Printf("更新了 %d 行\n", affected)

// ========== 删除数据 ==========
result, err = db.Exec("DELETE FROM user WHERE id = ?", 1)
if err != nil {
    return err
}
// 同时检查 error 和 sql.Result
// error 为 nil 不代表操作一定符合预期
// 比如删除了一个不存在的 ID，error 是 nil，但 RowsAffected 是 0
affected, _ = result.RowsAffected()
if affected == 0 {
    fmt.Println("没有删除任何行，可能 ID 不存在")
}

// ========== 查询单行数据 ==========
// QueryRow / QueryRowContext：查询单行数据
// 如果没有匹配的行，Scan 时会返回 sql.ErrNoRows
var name string
var age int
// QueryRow 返回 *sql.Row，不需要关闭
err := db.QueryRow("SELECT name, age FROM user WHERE id = ?", 1).
    Scan(&name, &age)
if err != nil {
    if err == sql.ErrNoRows {
        fmt.Println("没有找到记录")
    } else {
        fmt.Println("查询出错:", err)
    }
    return
}
fmt.Printf("name=%s, age=%d\n", name, age)

// ========== 查询多行数据 ==========
// Query / QueryContext：查询多行数据
// 返回 *sql.Rows，是一个迭代器，使用完毕必须关闭
rows, err := db.Query("SELECT id, name, age FROM user WHERE age > ?", 18)
if err != nil {
    return err
}
// defer Close 一定要写！否则会泄漏数据库连接
defer rows.Close()

// 迭代器设计：需要在使用前调用 Next 方法
// Next 返回 true 表示还有下一行，false 表示遍历结束
for rows.Next() {
    var id int64
    var name string
    var age int
    // Scan 支持的类型很多：基础类型、[]byte、string 等
    // 也可以传入实现了 sql.Scanner 接口的自定义类型
    err = rows.Scan(&id, &name, &age)
    if err != nil {
        return err
    }
    fmt.Printf("id=%d, name=%s, age=%d\n", id, name, age)
}

// 遍历结束后检查是否有错误
// Next 返回 false 可能是正常结束，也可能是出错
if err = rows.Err(); err != nil {
    return err
}

// Row 可以理解为只有一行的 Rows，而且是必须要有一行
// 如果没有匹配的行，Scan 会返回 sql.ErrNoRows

// QueryRow 的内部实现等价于：
// rows, err := db.Query(query, args...)
// if err != nil { return &Row{err: err} }
// defer rows.Close()
// if !rows.Next() {
//     if err := rows.Err(); err != nil {
//         return &Row{err: err}
//     }
//     return &Row{err: sql.ErrNoRows}
// }
// // 扫描数据...

package main

import (
    "database/sql"
    "database/sql/driver"
    "encoding/json"
    "fmt"
)

// JSON 自定义类型，用于在数据库中存储 JSON 数据
// 要实现两个接口：
// 1. driver.Valuer：Go 类型 -> 数据库类型（写入数据库时调用）
// 2. sql.Scanner：数据库类型 -> Go 类型（从数据库读取时调用）

type JSON struct {
    Data any
}

// ========== driver.Valuer 接口 ==========
// 写入数据库时调用
// 比如在 INSERT/UPDATE 时，将 JSON 序列化为 []byte
func (j JSON) Value() (driver.Value, error) {
    // driver.Value 只支持 int64, float64, bool, []byte, string, time.Time, nil
    // 所以我们将 JSON 序列化为 []byte
    if j.Data == nil {
        return nil, nil
    }
    bytes, err := json.Marshal(j.Data)
    if err != nil {
        return nil, err
    }
    return bytes, nil
}

// ========== sql.Scanner 接口 ==========
// 从数据库读取时调用
// 比如在 Scan 时，将数据库返回的 []byte 反序列化为 Go 类型
func (j *JSON) Scan(src any) error {
    if src == nil {
        j.Data = nil
        return nil
    }

    // 数据库返回的类型可能是 []byte 或 string
    var bytes []byte
    switch v := src.(type) {
    case []byte:
        bytes = v
    case string:
        bytes = []byte(v)
    default:
        return fmt.Errorf("无法将 %T 转换为 JSON", src)
    }

    // 反序列化
    return json.Unmarshal(bytes, &j.Data)
}

// 使用示例
func main() {
    type User struct {
        Id     int64
        Name   string
        Config JSON // 自定义类型，数据库中存储为 JSON 字符串
    }

    // 插入：driver.Valuer 接口会被自动调用
    // Config 会被序列化为 JSON 字符串存入数据库
    config := JSON{Data: map[string]any{"theme": "dark", "lang": "zh"}}
    db.Exec("INSERT INTO user(name, config) VALUES(?, ?)", "大明", config)

    // 查询：sql.Scanner 接口会被自动调用
    // 数据库返回的 JSON 字符串会被反序列化
    var u User
    var configJSON JSON
    db.QueryRow("SELECT name, config FROM user WHERE id = ?", 1).
        Scan(&u.Name, &configJSON)
    fmt.Printf("Config: %+v\n", configJSON.Data)
}

// ========== 传统事务 API ==========

// Begin 开启事务
// BeginTx 可以传入 TxOptions 来设置隔离级别
tx, err := db.Begin()
if err != nil {
    return err
}

// 在事务中执行操作（使用 tx 而不是 db）
_, err = tx.Exec("UPDATE account SET balance = balance - 100 WHERE id = ?", 1)
if err != nil {
    // 出错就回滚
    tx.Rollback()
    return err
}

_, err = tx.Exec("UPDATE account SET balance = balance + 100 WHERE id = ?", 2)
if err != nil {
    tx.Rollback()
    return err
}

// 成功就提交
err = tx.Commit()
if err != nil {
    return err
}

// ========== 使用 TxOptions 设置隔离级别 ==========
// 大多数时候我们不需要设置 TxOptions
// 逼不得已要设置 Isolation 字段时，要确认数据库支持该级别
tx, err = db.BeginTx(context.Background(), &sql.TxOptions{
    Isolation: sql.LevelRepeatableRead, // 可重复读
    ReadOnly:  false,                    // 是否只读
})

// MySQL 隔离级别在 Go 中的对应常量
var (
    // 序列化：事务与事务是挨个执行的，完全隔离
    // 性能最差，但数据一致性最好
    LevelSerializable = sql.LevelSerializable

    // 可重复读（MySQL 默认）：A 事务无法看到 B 事务的修改
    // A 事务内同一个 SELECT 语句执行的结果总是相同的
    // 注意：InnoDB 引擎在此级别下不会出现幻读
    LevelRepeatableRead = sql.LevelRepeatableRead

    // 已提交读：A 事务无法看到 B 事务未提交的修改
    // 但可以看到已提交的修改
    LevelReadCommitted = sql.LevelReadCommitted

    // 未提交读：A 事务能看到 B 事务未提交的修改
    // 性能最好，但数据一致性最差
    LevelReadUncommitted = sql.LevelReadUncommitted
)

// Prepare Statement（预编译语句）
// 优点：
// 1. 防止 SQL 注入
// 2. 提高性能（同一条 SQL 只编译一次）
// 3. 一般生命周期和整个应用的生命周期一致

// 在应用启动时预编译
stmt, err := db.Prepare("SELECT name, age FROM user WHERE id = ?")
if err != nil {
    panic(err)
}
defer stmt.Close()

// 后续多次使用
var name string
var age int
err = stmt.QueryRow(1).Scan(&name, &age)
err = stmt.QueryRow(2).Scan(&name, &age)

package orm_test

import (
    "database/sql"
    "testing"

    "github.com/DATA-DOG/go-sqlmock"
    "github.com/stretchr/testify/assert"
)

// TestSQLMock 演示 sqlmock 的基本用法
func TestSQLMock(t *testing.T) {
    // 初始化：返回一个 mockDB（类型是 *sql.DB）和 mock（用于构造模拟场景）
    db, mock, err := sqlmock.New()
    if err != nil {
        t.Fatal(err)
    }
    defer db.Close()

    // 设置 mock：ExpectXXX + WillXXX
    // 严格依赖于顺序：mock 查询顺序和实际查询顺序必须完全一致

    // 期望：查询 user 表，返回 id=1, name="大明", age=28
    rows := sqlmock.NewRows([]string{"id", "name", "age"}).
        AddRow(1, "大明", 28)
    // ExpectQuery：期望执行一条 SELECT 语句
    // WillReturnRows：模拟返回的行数据
    mock.ExpectQuery("SELECT id, name, age FROM user WHERE id = \\?").
        WithArgs(1). // 期望的参数值
        WillReturnRows(rows)

    // 执行真实的查询
    var id int64
    var name string
    var age int
    err = db.QueryRow("SELECT id, name, age FROM user WHERE id = ?", 1).
        Scan(&id, &name, &age)

    // 断言
    assert.NoError(t, err)
    assert.Equal(t, int64(1), id)
    assert.Equal(t, "大明", name)
    assert.Equal(t, 28, age)

    // 验证所有期望都被满足
    // 如果有期望没被满足，或者有额外的查询，都会报错
    if err := mock.ExpectationsWereMet(); err != nil {
        t.Errorf("未满足的期望: %v", err)
    }
}

// 模拟插入场景
func TestSQLMockInsert(t *testing.T) {
    db, mock, _ := sqlmock.New()
    defer db.Close()

    // 期望：执行 INSERT 语句
    // WillReturnResult：模拟返回的结果
    mock.ExpectExec("INSERT INTO user\\(name, age\\) VALUES\\(\\?, \\?\\)").
        WithArgs("大明", 28).
        WillReturnResult(sqlmock.NewResult(1, 1)) // LastInsertId=1, RowsAffected=1

    // 执行插入
    result, err := db.Exec("INSERT INTO user(name, age) VALUES(?, ?)", "大明", 28)
    assert.NoError(t, err)

    id, _ := result.LastInsertId()
    assert.Equal(t, int64(1), id)

    mock.ExpectationsWereMet()
}

// 模拟错误场景
func TestSQLMockError(t *testing.T) {
    db, mock, _ := sqlmock.New()
    defer db.Close()

    // 模拟查询返回错误
    mock.ExpectQuery("SELECT .+ FROM user WHERE id = \\?").
        WithArgs(999).
        WillReturnError(sql.ErrNoRows)

    var name string
    err := db.QueryRow("SELECT name FROM user WHERE id = ?", 999).Scan(&name)
    assert.Equal(t, sql.ErrNoRows, err)

    mock.ExpectationsWereMet()
}

// db.go 文件

import (
    "context"
    "database/sql"
)

// DB 代表一个数据库实例
// 它是 sql.DB 的一个封装
type DB struct {
    // db 是标准库的 sql.DB
    // sql.DB 应该和 ORM 层面上的 DB 概念绑定在一起
    db *sql.DB
    // registry 是元数据注册中心
    registry
}

// Open 使用驱动名和 DSN 创建 DB 实例
func Open(driver string, dsn string) (*DB, error) {
    db, err := sql.Open(driver, dsn)
    if err != nil {
        return nil, err
    }
    return &DB{
        db:       db,
        registry: newRegistry(),
    }, nil
}

// OpenDB 使用已有的 sql.DB 创建 DB 实例
// 常用于测试（配合 sqlmock）和集成别的数据库中间件
func OpenDB(db *sql.DB) (*DB, error) {
    return &DB{
        db:       db,
        registry: newRegistry(),
    }, nil
}

// Selector 的 Get 方法：查询单条数据
func (s *Selector[T]) Get(ctx context.Context) (*T, error) {
    // 1. 构建 SQL
    q, err := s.Build()
    if err != nil {
        return nil, err
    }

    // 2. 发起查询
    // 最好都用 QueryContext，这样能在 GetMulti 和 Get 之间复用代码
    rows, err := s.db.db.QueryContext(ctx, q.SQL, q.Args...)
    if err != nil {
        return nil, err
    }
    defer rows.Close()

    // 3. 处理结果集
    if !rows.Next() {
        // 没有数据
        return nil, ErrNoRows
    }

    // 创建目标结构体
    tp := new(T)

    // 获取元数据
    m, err := s.db.registry.Get(tp)
    if err != nil {
        return nil, err
    }

    // 处理结果集（将行数据填充到结构体）
    // 后面会用反射或 unsafe 来实现
    values := s.buildValues(m, tp)
    if err = rows.Scan(values...); err != nil {
        return nil, err
    }

    return tp, nil
}

// GetMulti 查询多条数据
func (s *Selector[T]) GetMulti(ctx context.Context) ([]*T, error) {
    q, err := s.Build()
    if err != nil {
        return nil, err
    }

    rows, err := s.db.db.QueryContext(ctx, q.SQL, q.Args...)
    if err != nil {
        return nil, err
    }
    defer rows.Close()

    var result []*T
    for rows.Next() {
        tp := new(T)
        m, err := s.db.registry.Get(tp)
        if err != nil {
            return nil, err
        }
        values := s.buildValues(m, tp)
        if err = rows.Scan(values...); err != nil {
            return nil, err
        }
        result = append(result, tp)
    }

    return result, nil
}

// reflect_value.go 文件

// reflectValue 使用反射处理结果集
type reflectValue struct {
    // model 缓存元数据，避免重复获取
    model *Model
    // val 是目标结构体的反射值
    val reflect.Value
}

// newReflectValue 创建一个 reflectValue 实例
func newReflectValue(model *Model, val any) *reflectValue {
    return &reflectValue{
        model: model,
        val:   reflect.ValueOf(val).Elem(), // 取指针指向的值
    }
}

// setColumns 返回用于 Scan 的参数列表
// 核心思路：为每个字段创建一个 reflect.Value 的指针
// Scan 会将数据库返回的值填充到这些指针中
func (r *reflectValue) setColumns() []any {
    // 按照列在 SQL 中的顺序，收集每个字段的可写地址
    res := make([]any, 0, len(r.model.FieldMap))
    for i := 0; i < r.val.NumField(); i++ {
        // 取字段的地址（Field(i).Addr() 返回字段的指针）
        // 注意：必须通过指针才能修改字段的值
        // 如果传入的是值而不是指针，Addr() 会 panic
        fd := r.val.Field(i)
        // 检查是否可以取地址
        if fd.CanAddr() {
            res = append(res, fd.Addr().Interface())
        }
    }
    return res
}

// 改进版：按照元数据中的列顺序来构造 Scan 参数
func (r *reflectValue) setColumns(columns []string) ([]any, error) {
    // columns 是数据库返回的列名列表
    // 我们需要按照这个顺序来构造参数
    res := make([]any, 0, len(columns))

    // 构建列名 -> 字段名的反向映射
    // 元数据中是 字段名 -> 列名 的映射
    // 这里需要反过来，根据列名找到字段名
    colToField := make(map[string]string, len(r.model.FieldMap))
    for fieldName, field := range r.model.FieldMap {
        colToField[field.ColName] = fieldName
    }

    for _, col := range columns {
        fieldName, ok := colToField[col]
        if !ok {
            // 数据库返回了一个我们不知道的列
            return nil, NewUnknownColumnError(col, r.model.TableName)
        }
        // 取字段的地址
        fd := r.val.FieldByName(fieldName)
        if !fd.CanAddr() {
            return nil, fmt.Errorf("字段 %s 无法取地址", fieldName)
        }
        res = append(res, fd.Addr().Interface())
    }

    return res, nil
}

package main

import (
    "fmt"
    "unsafe"
)

// User 演示内存对齐
type User struct {
    // 字段在内存中的布局（64位机器）：
    // Id:    offset 0,  size 8  (int64)
    // Age:   offset 8,  size 1  (int8)
    // agev1: offset 9,  size 1  (int8)
    // --- 10 字节，需要填充到 8 的倍数 ---
    // --- age 和 agev1 恰好凑成 2 字节，Alias 的偏移量仍然是 16 ---
    // 不对，实际上 Age(1) + agev1(1) = 2 字节，从 offset 8 开始
    // 下一个字段 Alias 是 string 类型，需要 8 字节对齐
    // 所以 8 + 2 = 10，填充到 16，Alias 的偏移量是 16？不对
    // 实际上 Age(1) + agev1(1) = 2，但从 offset 8 开始
    // offset 10 开始填充，下一个 8 字节对齐位置是 16
    // 所以 Alias 的偏移量是 16
    Id    int64   // offset 0,  size 8
    Age   int8    // offset 8,  size 1
    agev1 int8    // offset 9,  size 1
    Alias string  // offset 16, size 16 (string 在 64 位上是 16 字节：指针 + 长度)
}

func main() {
    u := User{}
    fmt.Println("结构体大小:", unsafe.Sizeof(u))
    // 输出: 64 (不对，实际应该是 8 + 1 + 1 + 6填充 + 16 = 32)
    // 让我们逐个字段看偏移量

    fmt.Println("Id offset:", unsafe.Offsetof(u.Id))     // 0
    fmt.Println("Age offset:", unsafe.Offsetof(u.Age))   // 8
    fmt.Println("Alias offset:", unsafe.Offsetof(u.Alias)) // 16

    // 为什么 Alias 的偏移量是 16 而不是 10？
    // 因为 Go 是按照字长来对齐的
    // 在 64 位机器上，string 类型的起始地址必须是 8 的倍数
    // Age + agev1 占了 offset 8~9，然后填充到 offset 16
    // 所以 Alias 的偏移量其实是 16
}

// unsafe.Pointer 和 uintptr 都代表"指针"，但有本质区别：

// unsafe.Pointer：Go 层面的指针
// GC 会维护 unsafe.Pointer 的值
// 如果 GC 时对象被移动（Go GC 是标记-复制算法），Pointer 会被自动修正
var p unsafe.Pointer

// uintptr：直接就是一个数字，代表一个内存地址
// GC 不会维护 uintptr 变量
// 如果 GC 时对象被移动，uintptr 不会更新，指向错误的地址
var addr uintptr

package main

import (
    "fmt"
    "unsafe"
)

func main() {
    type User struct {
        Name string
        Age  int
    }

    u := &User{Name: "大明", Age: 28}

    // ========== 正确用法 ==========
    // 1. 获取对象起始地址（unsafe.Pointer）
    ptr := unsafe.Pointer(u)
    fmt.Printf("对象起始地址: %p\n", ptr)

    // 2. 计算字段偏移量（uintptr，因为偏移量是固定的）
    ageOffset := unsafe.Offsetof(u.Age)
    fmt.Printf("Age 字段偏移量: %d\n", ageOffset)

    // 3. 计算字段真实地址
    // 字段真实地址 = 对象起始地址 + 字段偏移量
    // 注意：这里只在地址运算时使用 uintptr，运算完后立即转回 unsafe.Pointer
    agePtr := unsafe.Pointer(uintptr(ptr) + ageOffset)

    // 4. 读取字段值：*(*T)(ptr)
    // T 是目标类型，这里是 int
    age := *(*int)(agePtr)
    fmt.Printf("Age 值: %d\n", age) // 输出: 28

    // 5. 写入字段值：*(*T)(ptr) = newVal
    *(*int)(agePtr) = 29
    fmt.Printf("修改后 Age: %d\n", u.Age) // 输出: 29

    // ========== 如果类型不知道，用 reflect.NewAt ==========
    // 当你只有 reflect.Type 而没有具体类型时
    // 可以用 reflect.NewAt(typ, ptr).Elem() 在特定地址创建对象
    //
    // reflect.NewAt(typ, agePtr).Elem() 等价于 *(*int)(agePtr)
    // 但它返回 reflect.Value，更灵活
}

// unsafe_value.go 文件

import (
    "reflect"
    "unsafe"
)

// unsafeValue 使用 unsafe 处理结果集
// 相比反射方案，unsafe 直接在目的地建好对象，让 Scan 去填充
// 而反射则是在别的地方建好对象，Scan 填充内容，然后再拷贝到正确位置
type unsafeValue struct {
    model *Model
    // val 是目标结构体的指针（起始地址）
    val unsafe.Pointer
}

// newUnsafeValue 创建一个 unsafeValue 实例
func newUnsafeValue(model *Model, val any) *unsafeValue {
    return &unsafeValue{
        model: model,
        // 获取对象的起始地址
        // reflect.ValueOf(val).Pointer() 返回 uintptr
        // 转成 unsafe.Pointer 以便后续操作
        val: unsafe.Pointer(reflect.ValueOf(val).Pointer()),
    }
}

// setColumns 返回用于 Scan 的参数列表
// 核心思路：在每个字段的真实地址位置创建一个对象
func (u *unsafeValue) setColumns(columns []string) ([]any, error) {
    res := make([]any, 0, len(columns))

    // 构建列名 -> 字段元数据的反向映射
    colToField := make(map[string]*Field, len(u.model.FieldMap))
    for _, field := range u.model.FieldMap {
        colToField[field.ColName] = field
    }

    for _, col := range columns {
        field, ok := colToField[col]
        if !ok {
            return nil, NewUnknownColumnError(col, u.model.TableName)
        }

        // 计算字段真实地址
        // 字段真实地址 = 对象起始地址 + 字段偏移量
        // field.Offset 是 uintptr 类型，表示字段相对于结构体起始地址的偏移量
        // 这个偏移量是固定的，不管怎么 GC 都不会变
        fieldPtr := unsafe.Pointer(uintptr(u.val) + field.Offset)

        // 在 fieldPtr 这个位置创建一个字段对应类型的对象
        // reflect.NewAt(typ, ptr) 在 ptr 指向的地址创建一个 typ 类型的新对象
        // .Elem() 取出这个对象的 reflect.Value
        // .Addr() 取地址
        // .Interface() 转为 any
        val := reflect.NewAt(field.Type, fieldPtr).Elem().Addr().Interface()
        res = append(res, val)
    }

    return res, nil
}

// internal/model/model.go 文件

// 方案一：放到 internal 目录下
// internal 包特性：只有本项目能用，外部项目不能用
// 这样用户用不了我们的 registry，也就调用不了 Register 方法

// Model 代表一个模型的元数据
// 字段都是公有的，这样本项目的其它包都可以用
type Model struct {
    // TableName 是数据库表名
    TableName string
    // FieldMap 字段名 -> 字段元数据
    FieldMap map[string]*Field
    // ColumnMap 列名 -> 字段元数据（用于结果集处理）
    ColumnMap map[string]*Field
}

// Field 代表一个字段的元数据
type Field struct {
    // ColName 数据库列名
    ColName string
    // Type Go 类型
    Type reflect.Type
    // Offset 字段偏移量（用于 unsafe 结果集处理）
    // 定义为 uintptr 类型，因为偏移量是固定的，不管怎么 GC 都不会变
    Offset uintptr
    // IsPrimary 是否主键
    IsPrimary bool
    // IsIncrement 是否自增
    IsIncrement bool
}

// internal/model/registry.go 文件

// Registry 注册中心接口
type Registry interface {
    // Get 获取模型的元数据
    Get(val any) (*Model, error)
    // Register 注册模型，可附带自定义选项
    Register(val any, opts ...Option) (*Model, error)
}

// Option 模型注册的配置选项
// 注意：因为包名就叫 model，所以不能加 Model 前缀
// Go 里面不建议使用包名作为结构体名或方法名的前缀
// 例如 user 包里的服务应该叫 Service，而不是 UserService
type Option func(m *Model) error

// WithTableName 自定义表名
func WithTableName(name string) Option {
    return func(m *Model) error {
        m.TableName = name
        return nil
    }
}

// WithColumnName 自定义列名
func WithColumnName(field string, colName string) Option {
    return func(m *Model) error {
        fd, ok := m.FieldMap[field]
        if !ok {
            return fmt.Errorf("orm: 未知字段 %s", field)
        }
        // 更新 ColumnMap
        delete(m.ColumnMap, fd.ColName) // 删除旧的列名映射
        fd.ColName = colName
        m.ColumnMap[colName] = fd // 添加新的列名映射
        return nil
    }
}

// creator.go 文件

// Creator 是结果集处理器的工厂接口
// Selector 不应该知道究竟用的是 unsafe 还是反射
// 这符合"面向接口编程"的原则
type Creator func(model *model.Model, val any) Valuer

// Valuer 是结果集处理器的抽象
type Valuer interface {
    // setColumns 返回用于 Scan 的参数列表
    setColumns(columns []string) ([]any, error)
}

// ========== 反射实现 ==========
func newReflectValueCreator() Creator {
    return func(m *model.Model, val any) Valuer {
        return &reflectValue{
            model: m,
            val:   reflect.ValueOf(val).Elem(),
        }
    }
}

// ========== unsafe 实现 ==========
func newUnsafeValueCreator() Creator {
    return func(m *model.Model, val any) Valuer {
        return &unsafeValue{
            model: m,
            val:   unsafe.Pointer(reflect.ValueOf(val).Pointer()),
        }
    }
}

// ========== Selector 改造 ==========
type Selector[T any] struct {
    table   string
    where   []Predicate
    db      *DB
    // creator 决定使用反射还是 unsafe
    // 不使用 isUnsafe 这种布尔标记，因为那样 Selector 就知道了实现细节
    creator Creator
}

// 使用 unsafe 的选项
func (s *Selector[T]) UseUnsafe() *Selector[T] {
    s.creator = newUnsafeValueCreator()
    return s
}

// 使用反射的选项（默认）
func (s *Selector[T]) UseReflect() *Selector[T] {
    s.creator = newReflectValueCreator()
    return s
}

// Get 方法使用 creator 处理结果集
func (s *Selector[T]) Get(ctx context.Context) (*T, error) {
    // ... 构建 SQL、发起查询 ...

    tp := new(T)
    m, err := s.db.registry.Get(tp)
    if err != nil {
        return nil, err
    }

    // 使用 creator 创建结果集处理器
    // 如果用户没有指定，使用默认的反射实现
    creator := s.creator
    if creator == nil {
        creator = newReflectValueCreator()
    }
    valuer := creator(m, tp)

    // 获取列信息
    columns, err := rows.Columns()
    if err != nil {
        return nil, err
    }

    // 构造 Scan 参数
    values, err := valuer.setColumns(columns)
    if err != nil {
        return nil, err
    }

    // Scan
    if err = rows.Scan(values...); err != nil {
        return nil, err
    }

    return tp, nil
}

// benchmark_test.go 文件

// BenchmarkReflectGet 基准测试：反射方案
func BenchmarkReflectGet(b *testing.B) {
    // 初始化 DB（使用 sqlmock）
    db, mock, _ := sqlmock.New()
    defer db.Close()
    ormDB, _ := OpenDB(db)

    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        // 设置 mock
        mock.ExpectQuery("SELECT .* FROM .*").
            WillReturnRows(sqlmock.NewRows([]string{"id", "name", "age"}).
                AddRow(1, "大明", 28))

        // 使用反射查询
        _, _ = NewSelector[TestModel](ormDB).
            Get(context.Background())
    }
}

// BenchmarkUnsafeGet 基准测试：unsafe 方案
func BenchmarkUnsafeGet(b *testing.B) {
    db, mock, _ := sqlmock.New()
    defer db.Close()
    ormDB, _ := OpenDB(db)

    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        mock.ExpectQuery("SELECT .* FROM .*").
            WillReturnRows(sqlmock.NewRows([]string{"id", "name", "age"}).
                AddRow(1, "大明", 28))

        // 使用 unsafe 查询
        _, _ = NewSelector[TestModel](ormDB).
            UseUnsafe().
            Get(context.Background())
    }
}

// db.go 文件

// DBWithRegistry 允许用户指定在 DB 中使用的 Registry
// 用户可以实现自己的 Registry 接口
func DBWithRegistry(r model.Registry) DBOption {
    return func(db *DB) {
        db.registry = r
    }
}

// 使用示例
func main() {
    // 方式一：使用默认 Registry
    db, _ := Open("mysql", "root:password@tcp(127.0.0.1:3306)/test_db")

    // 方式二：使用自定义 Registry
    // customRegistry := &MyRegistry{...}
    // db, _ := OpenDB(sqlDB, DBWithRegistry(customRegistry))
}