四、事务 API、AOP 方案与集成测试

// Beego 的事务使用方式
o := orm.NewOrm()
err := o.Begin()  // 开启事务
if err != nil {
    return err
}
// 在事务中执行操作...
err = o.Commit()  // 提交
if err != nil {
    o.Rollback()  // 失败则回滚
}

// GORM 的事务闭包 API
err := db.Transaction(func(tx *gorm.DB) error {
    // 在事务中执行操作
    if err := tx.Create(&user).Error; err != nil {
        return err  // 返回 error 自动回滚
    }
    if err := tx.Create(&order).Error; err != nil {
        return err
    }
    return nil  // 返回 nil 自动提交
})

// tx.go 文件

// Tx 代表一个数据库事务
// 引入独立的 Tx 结构体，而不是让 DB 兼任事务角色
// 这样设计的好处：
//   1. DB 在创建后就是不可变的，职责清晰
//   2. 一个事务无法开启另一个事务（限制事务嵌套）
type Tx struct {
    // db 底层的 sql.Tx（标准库的事务对象）
    db *sql.Tx

    // valCreator 用于创建 valuer（处理结果集）
    // 从 DB 继承，保持事务内外的结果集处理方式一致
    valCreator valCreator

    // r 元数据注册中心
    // 从 DB 继承，事务内外共享同一份元数据缓存
    r registry
}

// Begin 开启一个事务
// 返回 Tx 实例，后续所有操作都通过 Tx 执行
func (db *DB) Begin(ctx context.Context, opts ...*sql.TxOptions) (*Tx, error) {
    // 调用标准库的 BeginTx
    // opts 是可选的事务选项（隔离级别、只读等）
    var txOpts *sql.TxOptions
    if len(opts) > 0 {
        txOpts = opts[0]
    }
    tx, err := db.db.BeginTx(ctx, txOpts)
    if err != nil {
        return nil, err
    }
    return &Tx{
        db:         tx,
        valCreator: db.valCreator,
        r:          db.r,
    }, nil
}

// Commit 提交事务
func (t *Tx) Commit() error {
    return t.db.Commit()
}

// Rollback 回滚事务
func (t *Tx) Rollback() error {
    return t.db.Rollback()
}

// session.go 文件

// Session 是 DB 和 Tx 的公共抽象
// 在 ORM 语境下，Session 代表一个上下文
// 可以理解为一种分组机制：在这个分组内，
// 所有的查询会共享一些基本的配置（如元数据、valuer 等）
type Session interface {
    // getCore 返回核心配置
    // Selector、Inserter 等构造器通过 core 来获取共享配置
    getCore() core

    // queryContext 执行查询（SELECT）
    queryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)

    // execContext 执行增删改（INSERT、UPDATE、DELETE）
    execContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}

// core 封装了 CRUD 操作都需要使用的公共配置
type core struct {
    // r 元数据注册中心
    r          registry
    // valCreator 结果集处理器工厂
    valCreator valCreator
    // dialect 方言
    dialect    Dialect
}

// db.go 文件

// DB 实现了 Session 接口
func (db *DB) getCore() core {
    return core{
        r:          db.r,
        valCreator: db.valCreator,
        dialect:    db.dialect,
    }
}

// DB 的查询和执行直接委托给内部的 sql.DB
func (db *DB) queryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error) {
    return db.db.QueryContext(ctx, query, args...)
}

func (db *DB) execContext(ctx context.Context, query string, args ...any) (sql.Result, error) {
    return db.db.ExecContext(ctx, query, args...)
}

// tx.go 文件

// Tx 实现了 Session 接口
func (t *Tx) getCore() core {
    return core{
        r:          t.r,
        valCreator: t.valCreator,
        dialect:    t.dialect,
    }
}

// Tx 的查询和执行委托给内部的 sql.Tx
// 所有操作都在同一个事务内执行
func (t *Tx) queryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error) {
    return t.db.QueryContext(ctx, query, args...)
}

func (t *Tx) execContext(ctx context.Context, query string, args ...any) (sql.Result, error) {
    return t.db.ExecContext(ctx, query, args...)
}

// selector.go 文件

// Selector 改造后接收 Session 而不是 DB
type Selector[T any] struct {
    core      // 组合 core，获取公共配置
    session Session  // 通过 session 执行 SQL
    // ... 其它字段
}

// NewSelector 创建 Selector
// 参数从 *DB 改为 Session
// 这样无论传入 DB 还是 Tx 都可以
func NewSelector[T any](sess Session) *Selector[T] {
    c := sess.getCore()
    return &Selector[T]{
        core:    c,
        session: sess,
    }
}

// 使用示例 —— 普通查询（无事务）
users, err := orm.NewSelector[User](db).  // db 实现了 Session
    Where(orm.C("Age").GT(18)).
    GetMulti(ctx)

// 使用示例 —— 事务查询
tx, err := db.Begin(ctx)
defer tx.RollbackIfNotCommit()  // 安全兜底
// tx 同样实现了 Session，可以传给 NewSelector
users, err = orm.NewSelector[User](tx).  // tx 实现了 Session
    Where(orm.C("Age").GT(18)).
    GetMulti(ctx)
err = tx.Commit()

// Beego 的事务闭包核心逻辑（简化版）
func (o *orm) DoTx(fn func(ctx context.Context, tx orm.Tx) error) error {
    panicked := true  // 标记是否发生了 panic
    tx, err := o.Begin()
    if err != nil {
        return err
    }

    // 使用 defer 来确保无论发生什么都能处理
    defer func() {
        // 如果发生了 panic，或者业务代码返回了 error，则回滚
        if panicked || err != nil {
            tx.Rollback()
            return
        }
        // 否则提交
        err = tx.Commit()
    }()

    // 执行用户的业务代码
    err = fn(context.Background(), tx)
    // 如果 fn 内部 panic，defer 中的 panicked 仍然是 true
    panicked = false  // 正常执行到这里说明没 panic
    return err
}

// tx.go 文件

// DoTx 是事务闭包 API
// 用户传入一个闭包函数 fn，ORM 自动管理事务生命周期：
//   - 如果 fn 返回 error 或发生 panic：回滚
//   - 如果 fn 正常返回 nil：提交
//
// 参数：
//   ctx: 上下文
//   fn:  用户的业务函数，接收事务上下文和 Tx 实例
func (db *DB) DoTx(ctx context.Context, fn func(ctx context.Context, tx *Tx) error) error {
    // 1. 开启事务
    tx, err := db.Begin(ctx)
    if err != nil {
        return err
    }

    // 2. 使用 defer 确保事务一定被处理
    //    panicked 标记是否发生了 panic
    //    Go 没有 try-catch，所以用 defer + recover 来捕获 panic
    panicked := true
    defer func() {
        if panicked || err != nil {
            // 发生 panic 或 error，回滚事务
            // 注意：回滚本身也可能出错，但我们只记录日志，不覆盖原始错误
            _ = tx.Rollback()
            return
        }
        // 正常完成，提交事务
        err = tx.Commit()
    }()

    // 3. 执行用户的业务代码
    //    如果 fn 内部 panic，defer 中的 panicked 仍为 true
    err = fn(ctx, tx)
    // 走到这里说明没有 panic
    panicked = false
    return err
}

// 使用示例：转账
err := db.DoTx(ctx, func(ctx context.Context, tx *Tx) error {
    // 从账户 A 扣款
    _, err := orm.NewInserter[Account](tx).
        // ... 执行扣款 ...
        Exec(ctx)
    if err != nil {
        return err  // 返回 error，ORM 自动回滚
    }

    // 向账户 B 加款
    _, err = orm.NewInserter[Account](tx).
        // ... 执行加款 ...
        Exec(ctx)
    if err != nil {
        return err
    }

    return nil  // 返回 nil，ORM 自动提交
})

// tx.go 文件

// RollbackIfNotCommit 如果事务没有被提交，就回滚
// 解决 Go 没有 try-catch 导致的重复回滚代码问题
//
// 原理：
//   如果事务已经被提交或回滚，调用 Rollback 会返回 sql.ErrTxDone
//   我们只需要忽略这个错误即可
func (t *Tx) RollbackIfNotCommit() error {
    err := t.db.Rollback()
    if err == sql.ErrTxDone {
        // 事务已经提交或回滚过了，忽略这个错误
        return nil
    }
    return err
}

// 使用示例：手动控制事务
func Transfer(db *DB, ctx context.Context, fromID, toID int64, amount float64) error {
    // 开启事务
    tx, err := db.Begin(ctx)
    if err != nil {
        return err
    }
    // 无论后续代码怎么走，只要还没提交，就回滚
    // 如果已经提交了，这个调用不会报错
    defer tx.RollbackIfNotCommit()

    // 扣款
    _, err = orm.NewUpdater[Account](tx).
        // ... 执行扣款 ...
        Exec(ctx)
    if err != nil {
        return err  // defer 中的 RollbackIfNotCommit 会回滚
    }

    // 加款
    _, err = orm.NewUpdater[Account](tx).
        // ... 执行加款 ...
        Exec(ctx)
    if err != nil {
        return err
    }

    // 提交事务
    // 提交成功后，defer 中的 RollbackIfNotCommit 会收到 ErrTxDone，忽略
    return tx.Commit()
}

// tx.go 文件

// txKey 是 context 中存储事务的 key 类型
// 使用自定义类型避免 key 冲突
type txKey struct{}

// BeginTx 开启事务，支持事务扩散
// 如果 context 中已经存在事务，直接返回该事务
// 否则创建新事务
func (db *DB) BeginTx(ctx context.Context, opts ...*sql.TxOptions) (*Tx, error) {
    // 1. 检查 context 中是否已有事务
    if tx, ok := ctx.Value(txKey{}).(*Tx); ok {
        // 已经在事务中，直接返回现有事务
        // 这就是事务传播的核心：上游有事务就用上游的
        return tx, nil
    }

    // 2. 没有事务，创建新事务
    tx, err := db.Begin(ctx, opts...)
    if err != nil {
        return nil, err
    }

    // 3. 将事务存入 context
    //    后续所有从该 context 创建的子 context 都能拿到这个事务
    // 注意：context 是不可变的，需要返回新的 context
    return tx, nil
}

// WithTx 将事务存入 context，返回新的 context
func WithTx(ctx context.Context, tx *Tx) context.Context {
    return context.WithValue(ctx, txKey{}, tx)
}

// GetTx 从 context 中获取事务（如果存在）
func GetTx(ctx context.Context) (*Tx, bool) {
    tx, ok := ctx.Value(txKey{}).(*Tx)
    return tx, ok
}

// 使用示例：事务扩散

// ServiceA 是上游方法，开启事务
func (s *ServiceA) DoSomething(ctx context.Context) error {
    tx, err := s.db.BeginTx(ctx)
    if err != nil {
        return err
    }
    defer tx.RollbackIfNotCommit()

    // 将事务放入 context
    ctx = orm.WithTx(ctx, tx)

    // 调用下游方法
    // 下游方法会通过 context 拿到同一个事务
    err = s.serviceB.DoOtherThing(ctx)
    if err != nil {
        return err
    }

    return tx.Commit()
}

// ServiceB 是下游方法，复用上游事务
func (s *ServiceB) DoOtherThing(ctx context.Context) error {
    // 如果 context 中有事务（上游开启了），则复用
    // 如果没有事务（上游没开启），则新建一个
    tx, err := s.db.BeginTx(ctx)
    if err != nil {
        return err
    }
    // 注意：如果是复用上游事务，不要在这里提交或回滚
    // 只有新建的事务才需要提交
    if _, ok := orm.GetTx(ctx); !ok {
        // 是新建的事务，需要管理生命周期
        defer tx.RollbackIfNotCommit()
        // ... 执行操作 ...
        return tx.Commit()
    }
    // 复用上游事务，直接执行操作即可
    // ... 执行操作 ...
    return nil
}

// 装饰器模式示例（非 Beego 原生）
type LoggingORM struct {
    inner orm.Ormer  // 被装饰的原始 ORM
}

func (l *LoggingORM) Insert(o interface{}) (int64, error) {
    start := time.Now()
    id, err := l.inner.Insert(o)
    log.Printf("Insert took %v, err=%v", time.Since(start), err)
    return id, err
}

// GORM Hook 示例

// BeforeCreate 在插入前被调用
func (u *User) BeforeCreate(tx *gorm.DB) error {
    // 可以修改即将插入的数据
    u.CreatedAt = time.Now()
    return nil
}

// AfterFind 在查询后被调用
func (u *User) AfterFind(tx *gorm.DB) error {
    // 可以对查询结果做后处理
    u.FullName = u.FirstName + " " + u.LastName
    return nil
}

// aop.go 文件

// ========== QueryContext 查询上下文 ==========
// 代表一次查询的上下文信息
// 包含查询类型、SQL、参数等
type QueryContext struct {
    // Type 查询类型：SELECT、INSERT、UPDATE、DELETE
    Type string

    // Model 元数据
    Model *Model

    // Builder SQL 构造器（Selector、Inserter 等）
    Builder QueryBuilder

    // Session 数据库会话（DB 或 Tx）
    Session Session

    // Ctx 上下文
    Ctx context.Context
}

// QueryBuilder 是能构造 SQL 的接口
type QueryBuilder interface {
    Build() (*Query, error)
}

// ========== QueryResult 查询结果 ==========
// 代表一次查询的结果
type QueryResult struct {
    // Result 查询结果（类型取决于查询类型）
    Result any

    // Err 错误信息
    Err error
}

// ========== Handler 处理器 ==========
// 代表在这个上下文里面"做点什么事情"
// Handler 是整个 AOP 链的终点——真正执行 SQL 的地方
type Handler interface {
    // Handle 执行查询
    Handle(ctx context.Context, qc *QueryContext) *QueryResult
}

// HandlerFunc 是 Handler 的函数适配器
// 让普通函数也能作为 Handler 使用
type HandlerFunc func(ctx context.Context, qc *QueryContext) *QueryResult

func (f HandlerFunc) Handle(ctx context.Context, qc *QueryContext) *QueryResult {
    return f(ctx, qc)
}

// ========== Middleware 中间件 ==========
// 连接不同的 Handler，形成洋葱模型
// 和 Web 框架的 Middleware 一模一样
type Middleware func(next Handler) Handler

// ========== 构建中间件链 ==========
// 将多个 Middleware 和一个最终的 Handler 组合成一条链
func BuildChain(handler Handler, ms ...Middleware) Handler {
    // 从后往前遍历，逐层包装
    // 效果：最后添加的 Middleware 在最外层
    for i := len(ms) - 1; i >= 0; i-- {
        handler = ms[i](handler)
    }
    return handler
}

// middleware_log.go 文件

// LogMiddleware 记录 SQL 执行日志
// 类似 Web 框架的 access log
//
// 优点（相比侵入式的 DEBUG 标记位）：
//   1. 无侵入——不需要修改 Get、GetMulti、Exec 等方法
//   2. 用户可控性更强——可以自由决定记录什么、怎么记录
func LogMiddleware(logFunc func(query string, args []any, err error, duration time.Duration)) Middleware {
    return func(next Handler) Handler {
        return HandlerFunc(func(ctx context.Context, qc *QueryContext) *QueryResult {
            // 1. 前置：构造 SQL
            //    如果构造就失败了，可以直接返回
            //    也可以选择继续执行，让后续中间件处理
            q, err := qc.Builder.Build()
            if err != nil {
                // SQL 构造失败，直接返回
                return &QueryResult{Err: err}
            }

            // 2. 记录开始时间
            start := time.Now()

            // 3. 调用下一个 Handler（继续执行洋葱链）
            res := next.Handle(ctx, qc)

            // 4. 后置：记录日志
            //    注意：args 中可能包含敏感信息（如密码）
            //    logFunc 的提供者需要自己处理脱敏
            logFunc(q.SQL, q.Args, res.Err, time.Since(start))

            return res
        })
    }
}

// 使用示例
db.Use(orm.LogMiddleware(func(sql string, args []any, err error, d time.Duration) {
    // 用户自己决定怎么记录
    // 注意处理敏感信息！
    log.Printf("[SQL] %s | args: %v | err: %v | duration: %v", sql, args, err, d)
}))

// middleware_otel.go 文件

// OtelMiddleware 使用 OpenTelemetry 记录追踪信息
// 和 Web 框架的追踪中间件类似
func OtelMiddleware(tracer trace.Tracer) Middleware {
    return func(next Handler) Handler {
        return HandlerFunc(func(ctx context.Context, qc *QueryContext) *QueryResult {
            // 1. 构造 SQL（用于 span 名称）
            q, err := qc.Builder.Build()
            if err != nil {
                return &QueryResult{Err: err}
            }

            // 2. 开启一个 span
            //    名称用表名 + 查询类型，例如 "user:SELECT"
            ctx, span := tracer.Start(ctx, qc.Model.TableName+":"+qc.Type)
            defer span.End()

            // 3. 记录属性
            span.SetAttributes(
                attribute.String("db.statement", q.SQL),
                // 注意：这里没有记录参数
                // 因为参数可能包含敏感信息
                // 如果要记录，需要处理加密/脱敏
            )

            // 4. 执行查询
            res := next.Handle(ctx, qc)

            // 5. 记录结果
            if res.Err != nil {
                span.RecordError(res.Err)
                span.SetStatus(codes.Error, res.Err.Error())
            }

            return res
        })
    }
}

// middleware_prom.go 文件

// PromMiddleware 使用 Prometheus 监控 SQL 执行
// 记录操作类型和对应的表
func PromMiddleware(counter prometheus.CounterVec) Middleware {
    return func(next Handler) Handler {
        return HandlerFunc(func(ctx context.Context, qc *QueryContext) *QueryResult {
            // 1. 构造 SQL
            q, err := qc.Builder.Build()
            if err != nil {
                return &QueryResult{Err: err}
            }

            // 2. 记录指标
            counter.WithLabelValues(
                qc.Type,              // 操作类型：SELECT、INSERT...
                qc.Model.TableName,   // 表名
            ).Inc()

            // 3. 执行查询
            return next.Handle(ctx, qc)

            // 注意：ORM 层面拿不到 IP 等信息
            // 因为 ORM 并不知道 sql 包内部的连接信息
            // 对于分库分表的数据库，这种监控可能过于粗糙
            // 因为在分库分表下，我们希望能单独监控每一个库
        })
    }
}

// 用户自定义 Middleware 可能需要的类型断言
func MyMiddleware(next Handler) Handler {
    return HandlerFunc(func(ctx context.Context, qc *QueryContext) *QueryResult {
        // 需要判断查询类型
        switch qc.Type {
        case "SELECT":
            // 需要类型断言才能拿到 Selector
            selector, ok := qc.Builder.(*Selector[User])
            if ok {
                // 可以访问 Selector 特有的方法
                _ = selector
            }
        case "INSERT":
            inserter, ok := qc.Builder.(*Inserter[User])
            if ok {
                _ = inserter
            }
        }
        return next.Handle(ctx, qc)
    })
}

# docker-compose.yml
version: '3'
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: test_db
    ports:
      - "3306:3306"
    # 健康检查，确保 MySQL 完全启动
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      timeout: 3s
      retries: 10

// integration/insert_test.go 文件

package integration

import (
    "context"
    "testing"

    "github.com/stretchr/testify/suite"
)

// InsertTestSuite 是 INSERT 操作的集成测试套件
type InsertTestSuite struct {
    // suite.Suite 提供了丰富的断言方法
    // 以及生命周期回调
    suite.Suite

    // db ORM 的 DB 实例
    db *orm.DB

    // driver 当前测试使用的数据库驱动名
    // 通过这个字段，可以用不同数据库运行同一个套件
    driver string
    // dsn 数据库连接字符串
    dsn    string
}

// SetupSuite 在整个套件开始前执行一次
// 用于初始化测试环境
func (s *InsertTestSuite) SetupSuite() {
    // 1. 创建 DB 实例
    db, err := orm.Open(s.driver, s.dsn)
    s.Require().NoError(err)
    s.db = db

    // 2. 创建测试表
    _, err = s.db.db.Exec(`
        CREATE TABLE IF NOT EXISTS user (
            id BIGINT AUTO_INCREMENT PRIMARY KEY,
            first_name VARCHAR(64) NOT NULL,
            last_name VARCHAR(64) NOT NULL,
            age INT NOT NULL DEFAULT 0
        )
    `)
    s.Require().NoError(err)
}

// TearDownTest 在每个测试用例结束后执行
// 用于清理每个测试产生的数据
// 这样每个测试用例都是独立的，不会互相影响
func (s *InsertTestSuite) TearDownTest() {
    // 清空测试表
    _, err := s.db.db.Exec("TRUNCATE TABLE user")
    s.Require().NoError(err)
}

// TearDownSuite 在整个套件结束后执行
func (s *InsertTestSuite) TearDownSuite() {
    // 关闭数据库连接
    s.db.Close()
}

// TestInsert 单条插入测试
func (s *InsertTestSuite) TestInsert() {
    t := s.T()
    ctx := context.Background()

    // 构造测试数据
    u := &User{
        FirstName: "大明",
        LastName:  "李",
        Age:       28,
    }

    // 执行插入
    res := orm.NewInserter[User](s.db).
        Values(u).
        Exec(ctx)

    // 验证结果
    affected, err := res.RowsAffected()
    s.NoError(err)
    s.Equal(int64(1), affected)  // 应该影响 1 行

    // 验证自增 ID
    id, err := res.LastInsertId()
    s.NoError(err)
    s.True(id > 0)  // 自增 ID 应该大于 0
}

// TestInsertBatch 批量插入测试
func (s *InsertTestSuite) TestInsertBatch() {
    ctx := context.Background()

    users := []*User{
        {FirstName: "大明", LastName: "李", Age: 28},
        {FirstName: "小明", LastName: "王", Age: 25},
        {FirstName: "小红", LastName: "张", Age: 30},
    }

    res := orm.NewInserter[User](s.db).
        Values(users[0], users[1], users[2]).
        Exec(ctx)

    affected, err := res.RowsAffected()
    s.NoError(err)
    s.Equal(int64(3), affected)  // 应该影响 3 行
}

// TestInsertSuite 运行测试套件
// 这是 Go test 的入口
func TestInsertSuite(t *testing.T) {
    // 可以用不同数据库运行同一个套件
    suite.Run(t, &InsertTestSuite{
        driver: "mysql",
        dsn:    "root:root@tcp(localhost:3306)/test_db",
    })

    // 也可以测试 SQLite3
    // suite.Run(t, &InsertTestSuite{
    //     driver: "sqlite3",
    //     dsn:    "file:test.db?cache=shared&mode=memory",
    // })
}

// integration/select_test.go 文件

type SelectTestSuite struct {
    suite.Suite
    db     *orm.DB
    driver string
    dsn    string
}

// SetupSuite 在套件开始前一次性准备好所有测试数据
func (s *SelectTestSuite) SetupSuite() {
    // 创建 DB 和表...
    // 省略创建过程

    // 一次性插入所有测试数据
    // SELECT 不修改数据，所以可以一次性准备好
    users := []*User{
        {Id: 1, FirstName: "大明", LastName: "李", Age: 28},
        {Id: 2, FirstName: "小明", LastName: "王", Age: 25},
        {Id: 3, FirstName: "小红", LastName: "张", Age: 30},
        {Id: 4, FirstName: "大强", LastName: "赵", Age: 35},
    }
    orm.NewInserter[User](s.db).Values(users...).Exec(context.Background())
}

// TearDownSuite 在套件结束后清理
// 只需要在最后清理一次即可
func (s *SelectTestSuite) TearDownSuite() {
    _, _ = s.db.db.Exec("DROP TABLE IF EXISTS user")
    s.db.Close()
}

// 注意：SELECT 测试套件不需要 TearDownTest
// 因为 SELECT 不会修改数据

func (s *SelectTestSuite) TestGet() {
    ctx := context.Background()

    u, err := orm.NewSelector[User](s.db).
        Where(orm.C("Id").EQ(1)).
        Get(ctx)

    s.NoError(err)
    s.NotNil(u)
    s.Equal("大明", u.FirstName)
}

func (s *SelectTestSuite) TestGetMulti() {
    ctx := context.Background()

    users, err := orm.NewSelector[User](s.db).
        Where(orm.C("Age").GT(20)).
        GetMulti(ctx)

    s.NoError(err)
    s.Len(users, 4)  // 年龄大于 20 的有 4 个
}

func TestSelectSuite(t *testing.T) {
    suite.Run(t, &SelectTestSuite{
        driver: "mysql",
        dsn:    "root:root@tcp(localhost:3306)/test_db",
    })
}

// integration/suite.go 文件

// ORMTestSuite 是所有 ORM 集成测试的公共基类
// 封装了公共的初始化和清理逻辑
type ORMTestSuite struct {
    suite.Suite

    db     *orm.DB
    driver string
    dsn    string
}

// SetupSuite 公共的初始化逻辑
func (s *ORMTestSuite) SetupSuite() {
    db, err := orm.Open(s.driver, s.dsn)
    s.Require().NoError(err)
    s.db = db

    // 创建表
    s.createTable()
}

// TearDownSuite 公共的清理逻辑
func (s *ORMTestSuite) TearDownSuite() {
    _, _ = s.db.db.Exec("DROP TABLE IF EXISTS user")
    s.db.Close()
}

// createTable 创建测试表
func (s *ORMTestSuite) createTable() {
    _, err := s.db.db.Exec(`
        CREATE TABLE IF NOT EXISTS user (
            id BIGINT AUTO_INCREMENT PRIMARY KEY,
            first_name VARCHAR(64) NOT NULL,
            last_name VARCHAR(64) NOT NULL,
            age INT NOT NULL DEFAULT 0
        )
    `)
    s.Require().NoError(err)
}

// InsertTestSuite 继承 ORMTestSuite
type InsertTestSuite struct {
    ORMTestSuite  // 组合公共基类
}

// 重写 SetupSuite，先调用父类的，再执行自己的逻辑
func (s *InsertTestSuite) SetupSuite() {
    s.ORMTestSuite.SetupSuite()  // 调用公共初始化
    // INSERT 测试需要每个测试后清理数据
}

// TearDownTest 每个测试后清理
func (s *InsertTestSuite) TearDownTest() {
    _, _ = s.db.db.Exec("TRUNCATE TABLE user")
}

// SelectTestSuite 继承 ORMTestSuite
type SelectTestSuite struct {
    ORMTestSuite  // 组合公共基类
}

// 重写 SetupSuite，先调用父类的，再插入测试数据
func (s *SelectTestSuite) SetupSuite() {
    s.ORMTestSuite.SetupSuite()  // 调用公共初始化
    // 一次性插入 SELECT 测试所需的数据
    users := []*User{
        {FirstName: "大明", LastName: "李", Age: 28},
        {FirstName: "小明", LastName: "王", Age: 25},
    }
    orm.NewInserter[User](s.db).Values(users...).Exec(context.Background())
}

// 集中式示例：在 SetupSuite 中一次性准备好所有数据
func (s *SelectTestSuite) SetupSuite() {
    s.ORMTestSuite.SetupSuite()
    // 一次性插入所有测试数据
    users := []*User{
        {Id: 1, FirstName: "大明", LastName: "李", Age: 28},
        {Id: 2, FirstName: "小明", LastName: "王", Age: 25},
        // ... 更多数据
    }
    orm.NewInserter[User](s.db).Values(users...).Exec(context.Background())
}

// 分散式示例：每个测试自己准备数据
func (s *InsertTestSuite) TestInsert() {
    // 每个测试自己创建数据
    u := &User{FirstName: "大明", LastName: "李", Age: 28}
    // ...
}

//go:build e2e

// 注意：//go:build 必须在 package 声明之上，中间不能有空行
package integration

import (
    "testing"
    // ...
)

func TestInsertSuite(t *testing.T) {
    // ...
}

// 运行命令
// 只运行单元测试（不包含 e2e 标签的文件）
go test ./...

// 运行单元测试 + 集成测试
go test -tags=e2e ./...

# Makefile 中加入集成测试命令
orm_e2e:
	docker-compose up -d mysql
	# 等待数据库启动
	go test -tags=e2e ./...
	docker-compose down

// integration/setup.go 文件

// waitForDB 等待数据库就绪
// 在没有连上之前，不会运行后续测试
func waitForDB(dsn string, maxRetry int) error {
    db, err := sql.Open("mysql", dsn)
    if err != nil {
        return err
    }
    defer db.Close()

    // 重试连接
    for i := 0; i < maxRetry; i++ {
        err = db.Ping()
        if err == nil {
            return nil  // 连接成功
        }
        // 连接失败，等待后重试
        time.Sleep(time.Second)
    }
    return fmt.Errorf("数据库连接超时: %w", err)
}

// 在 TestMain 中等待数据库就绪
func TestMain(m *testing.M) {
    // 等待数据库启动
    if err := waitForDB("root:root@tcp(localhost:3306)/test_db", 30); err != nil {
        log.Fatal(err)
    }
    // 运行测试
    os.Exit(m.Run())
}

// raw.go 文件

// RawQuerier 原生查询器
// 允许用户直接写 SQL，绕过 ORM 的 SQL 构造机制
// 适用于：
//   1. ORM 不支持的高级语法
//   2. 复杂的联表查询
//   3. 数据库特有的函数
type RawQuerier[T any] struct {
    core
    session Session

    // sql 原始 SQL 语句
    sql string
    // args SQL 参数
    args []any
}

// Raw 创建原生查询器
// 用法：
//   orm.Raw[User]("SELECT * FROM user WHERE id = ?", 1)
//   orm.Raw[User]("SELECT * FROM user WHERE age > ? AND age < ?", 18, 60)
func Raw[T any](sess Session, sql string, args ...any) *RawQuerier[T] {
    c := sess.getCore()
    return &RawQuerier[T]{
        core:    c,
        session: sess,
        sql:     sql,
        args:    args,
    }
}

// Get 执行原生查询，返回单条记录
func (r *RawQuerier[T]) Get(ctx context.Context) (*T, error) {
    // 直接执行用户提供的 SQL
    rows, err := r.session.queryContext(ctx, r.sql, r.args...)
    if err != nil {
        return nil, err
    }

    for rows.Next() {
        res := new(T)
        // 复用 valuer 处理结果集
        val := r.valCreator(r.model, res)
        // ... 扫描数据 ...
        return res, nil
    }
    return nil, ErrNoRows
}

// Exec 执行原生 SQL（INSERT/UPDATE/DELETE）
func (r *RawQuerier[T]) Exec(ctx context.Context) *Result {
    res, err := r.session.execContext(ctx, r.sql, r.args...)
    return &Result{result: res, err: err}
}

// 使用示例

// 原生 SELECT
user, err := orm.Raw[User](db,
    "SELECT * FROM user WHERE id = ?", 1).
    Get(ctx)

// 复杂的联表查询（ORM 难以支持）
type OrderDetail struct {
    OrderID    int64
    UserName   string
    ProductName string
    Quantity   int
}
details, err := orm.Raw[OrderDetail](db,
    `SELECT o.id as order_id, u.name as user_name, p.name as product_name, oi.quantity
     FROM orders o
     JOIN user u ON o.user_id = u.id
     JOIN order_item oi ON o.id = oi.order_id
     JOIN product p ON oi.product_id = p.id
     WHERE o.status = ?`, "paid").
    GetMulti(ctx)

// 原生 INSERT
res := orm.Raw[User](db,
    "INSERT INTO user(name, age) VALUES(?, ?)", "大明", 28).
    Exec(ctx)