结论：gin 搭配 sqlx 是轻量可控的数据库方案，适合中小项目；sqlx.connect() = sql.open() + db.ping()，确保启动时验证连接，生产环境必须使用，避免“假连上”；需手动处理建表、orm 映射、嵌套结构、事务显式传 *sqlx.tx、db tag 规范、连接池调优及时区配置。
直接说结论：用 Gin 搭配 sqlx 是轻量、可控、无魔法的数据库集成方案，适合中小项目或需要精细控制 SQL 的场景；但要注意它不自动建表、不带 ORM 关系映射、也不处理嵌套结构——这些都得你手写。
sqlx.Connect() 和 sql.Open() 的区别必须搞清
sqlx.Connect() = sql.Open() + db.Ping()，它会真正尝试连一次数据库并校验凭证。而 sql.Open() 只是初始化连接池配置，返回后可能 db 仍是“假连上”状态，后续第一次查询才暴露问题。
- 生产环境务必用
sqlx.Connect()，否则服务启动时无法发现数据库不可达 - 如果用
sql.Open()，必须手动加db.Ping()并检查错误，否则 panic 或静默失败 -
sqlx.Connect()的第二个返回值是error，别忽略它——常见错误如dial tcp 127.0.0.1:3306: connect: connection refused
struct tag 里 db:"xxx" 不生效？检查三件事
你定义了 type User struct { ID int `db:"id"` }，但 db.Get() 或 db.Select() 读不出数据，大概率是 tag 写错了或没被识别。
- 确保字段首字母大写（Go 导出规则），
id int不会被反射读取，必须写成ID int - 确认用了
db:"id"，不是json:"id"或gorm:"column:id"——sqlx只认dbtag - 如果字段类型和数据库列类型不匹配（比如 MySQL
TINYINT(1)映射到 Goint没问题，但映射到bool就要加sql.NullBool或自定义 Scanner）
事务里用 sqlx 必须显式传 *sqlx.Tx
sqlx 的事务不是靠上下文或全局变量隐式传递的，所有操作必须显式把 *sqlx.Tx 当参数传进去，否则还是走默认连接池，事务失效。
- 正确姿势：
tx, _ := db.Beginx()→tx.QueryRowx(...)→tx.Commit() - 错误写法：在事务块里直接调
db.QueryRowx(...)，这会绕过事务，变成独立提交 - 别忘了
defer tx.Rollback()放在Beginx()后，再用if err != nil { return }提前退出前手动tx.Commit()
Gin handler 里怎么安全复用 sqlx.DB 实例
全局单例 *sqlx.DB 是线程安全的，可直接在 Gin handler 中使用，但要注意初始化时机和连接池配置。
- DB 实例应在
main()开头就初始化并完成Ping()，不能在 handler 里懒加载——否则并发请求可能触发多次重复初始化 -
db.SetMaxOpenConns(20)和db.SetMaxIdleConns(10)要根据实际 QPS 调整，设太大容易耗尽 MySQL 连接数，太小会频繁创建/销毁连接 - 别在 handler 里调
db.Close()——这是全局资源，关了整个服务就断库了
最易被忽略的一点：sqlx 不处理时间时区。MySQL 返回的 DATETIME 默认按本地时区解析，如果你的服务部署在 UTC 服务器但数据库存的是北京时间，time.Time 字段会错 8 小时。解决方案是 DSN 加 loc=Asia%2FShanghai，且确保 Go 进程也设置了对应时区，否则 parseTime=True 也没用。
