Go项目应封装数据库操作以剥离连接管理、错误处理、事务控制和SQL组织；用sqlx替代database/sql提升开发效率，注意正确初始化、命名参数和结构体映射；SQL应外置到文件并用embed加载；事务需显式传递*sqlx.Tx；推荐用Querier接口统一DB与Tx调用。
Go 项目里直接在业务逻辑里写 db.Query 或 db.Exec 是不可维护的，封装数据库操作的核心目标不是“写个 DAO 层”，而是把连接管理、错误处理、事务控制、SQL 组织这四件事从 handler 或 service 里剥离出去。
用 sqlx 替代原生 database/sql
原生 database/sql 只提供最底层接口，连结构体自动扫描都要手写 Scan，容易出错且冗长。sqlx 在保持完全兼容的前提下，增加了命名参数、结构体映射、批量查询等实用能力。
常见错误：用 sqlx.DB 却没调用 sqlx.MustConnect 或忽略返回的 error，导致后续查询 panic；或误以为 sqlx.StructScan 能自动处理嵌套结构体（它不能）。
- 安装：
go get github.com/jmoiron/sqlx - 初始化时务必检查 error：
db, err := sqlx.Connect("mysql", dsn) if err != nil { log.Fatal(err) } - 使用命名参数（比
?更易维护）：db.Select(&users, "SELECT * FROM users WHERE age > :min_age", map[string]interface{}{"min_age": 18}) - 字段名必须和 struct tag 匹配，例如
type User struct { ID int `db:"id"` Name string `db:"name"` }
把 SQL 拆进单独的 .sql 文件里
硬编码 SQL 字符串会让重构和审计变得困难，尤其当语句含多表 JOIN 或动态条件时。把 SQL 提到外部文件，配合 embed（Go 1.16+）加载，既保类型安全又方便 DBA 审查。
立即学习“go语言免费学习笔记（深入）”；
典型陷阱：SQL 文件路径拼错导致运行时报 stat xxx.sql: no such file；或忘记用 //go:embed 注释触发 embed 机制。
- 目录结构示例：
sql/user_get_by_id.sql - 加载方式：
//go:embed sql/*.sql var sqlFS embed.FS
query, _ := fs.ReadFile(sqlFS, "sql/user_get_by_id.sql") db.Get(&user, query, id)
- 避免在 SQL 文件中写占位符如
:id后又用fmt.Sprintf拼接——这会引入 SQL 注入风险，应始终交由sqlx参数绑定处理
事务操作必须显式控制生命周期
Go 的 sqlx.Tx 不是上下文感知的，不会自动传播。你在 service 层开启事务后，必须把 *sqlx.Tx 实例显式传给所有相关 repository 方法，而不是在每个方法里调 db.Beginx()。
高频翻车点：事务内调用另一个未接收 tx 参数的 repo 方法，结果该操作跑在独立连接上，不参与回滚；或 defer tx.Rollback() 后忘了在成功时 tx.Commit()。
- 正确姿势：
tx, _ := db.Beginx() defer tx.Rollback()
userRepo := NewUserRepo(tx) // 把 tx 传进去 orderRepo := NewOrderRepo(tx)
if err := userRepo.Create(ctx, &u); err != nil { return err } if err := orderRepo.Create(ctx, &o); err != nil { return err }
return tx.Commit()
- 不要在 repo 方法签名里放
*sqlx.DB和*sqlx.Tx两个参数——用 interface 封装更清晰，比如定义Querier interface { Get(...), Select(...), Exec(...) }，让*sqlx.DB和*sqlx.Tx都实现它
真正难的不是怎么封装，而是决定哪些操作该进 repo、哪些该留在 service。比如“扣库存并发消息”这种跨资源动作，别强行塞进 UserRepo；而“根据用户 ID 查最近三条订单”这种明确的数据访问意图，就该是 OrderRepo.FindRecentByUserID 的职责。边界模糊时，优先让 repo 只做单表 CRUD + 明确关联查询，复杂编排交给 service。
