sqlx.Open后必须立即调用db.Ping()验证连接有效性，因sqlx.Open仅校验DSN格式、注册驱动、初始化连接池，不建立真实连接；未Ping则首请求易报connection refused或超时。
sqlx.Open 之后必须调用 db.Ping() 检查连接有效性
很多同学以为 sqlx.Open() 成功就代表能连上 MySQL，其实它只校验 DSN 格式，不发起真实连接。没加 db.Ping() 导致上线后首请求超时、报 "connection refused" 或空指针 panic 的情况很常见。
正确做法是初始化后立刻检查：
db, err := sqlx.Open("mysql", "user:pass@tcp(127.0.0.1:3306)/test?parseTime=true")
if err != nil {
log.Fatal(err)
}
if err = db.Ping(); err != nil { // 必须加
log.Fatal("failed to ping db:", err)
}
-
parseTime=true是关键参数，否则time.Time字段会扫描失败，报"can't scan into dest" - 推荐设
db.SetMaxOpenConns(20)和db.SetMaxIdleConns(10)，避免连接数失控 - 如果用 Docker 或远程地址，
tcp(127.0.0.1:3306)要换成实际 host:port，本地 macOS Docker 里常用host.docker.internal:3306
结构体字段名必须匹配数据库列名或用 db 标签显式指定
sqlx 默认按结构体字段名（非 tag）映射列，且**区分大小写**。MySQL 列名通常是小写蛇形（user_name），而 Go 字段习惯大驼峰（UserName），不加标签就会扫不到数据，返回零值但无错误。
两种可靠写法：
win可用的mysql指令skill
下载
安装、修复、更新或打包一个基于 Python 和 PyMySQL 实现的 Windows `mysql` 命令。适用于用户希望在 PowerShell/CMD 中输入 `mysql` 时重定向到 Python 实现、需要交互式输入 MySQL 连接信息、需要同步到当前用户本地 bin 目录，或需要将该能力封装成可公开复用的 Codex skill。
立即学习“go语言免费学习笔记（深入）”；
// 方式一：用 db 标签（推荐，显式可控）
type User struct {
ID int `db:"id"`
UserName string `db:"user_name"`
CreatedAt time.Time `db:"created_at"`
}
// 方式二：让字段名和列名完全一致（不推荐，违反 Go 命名规范）
type User struct {
Id int `db:"id"`
User_name string `db:"user_name"` // 字段名含下划线，难看且无法导出
}
- 所有字段若需被扫描，必须是**可导出的（首字母大写）**，否则 sqlx 直接跳过
-
db:标签值支持别名，也支持-表示忽略该字段：DeletedAt time.Time `db:"-"` - 如果表有
updated_at但结构体没对应字段，sqlx 不报错也不警告——得靠日志或单元测试覆盖验证
Queryx + StructScan 是最安全的单行/多行查询模式
别用 db.Query() 配原生 rows.Scan()，容易漏字段、顺序错、类型不匹配。sqlx 提供的 Get() / Select() 封装更稳，但要注意它们底层仍依赖 StructScan 的字段对齐逻辑。
// 查单行：用 Get() var u User err := db.Get(&u, "SELECT id, user_name, created_at FROM users WHERE id = ?", 123) // 查多行：用 Select() var users []User err := db.Select(&users, "SELECT id, user_name, created_at FROM users WHERE status = ?", "active")
-
Get()要求 SQL 最多返回一行，返回 0 行时 err == nil，u 是零值；返回多行则报"sql: expected 1 row, got 3" -
Select()对空结果集友好，users会是空切片，不是 nil - 如果 SQL 里用了列别名（如
SELECT user_name AS name），结构体字段标签必须对应别名：Name string `db:"name"` - 注意
db.Get()第二个参数是 *destination*，必须传指针；db.Select()也是，传&users而非users
NamedExec 处理 map 或结构体参数时，字段名必须全小写或严格匹配标签
用 NamedExec 插入或更新时，如果传结构体，sqlx 会按字段名（非 db 标签）找占位符；传 map[string]interface{} 则 key 必须小写，否则找不到绑定值，报 "missing destination name"。
// 正确：结构体字段名与 SQL 中 :xxx 一致（注意大小写）
_, err := db.NamedExec("INSERT INTO users (user_name) VALUES (:user_name)", User{UserName: "alice"})
// 正确：map 的 key 全小写
_, err := db.NamedExec("INSERT INTO users (user_name) VALUES (:user_name)",
map[string]interface{}{"user_name": "bob"})
// 错误：map key 大驼峰 → 找不到 :UserName
db.NamedExec("...", map[string]interface{}{"UserName": "bob"})
- SQL 中的命名参数（
:user_name）和结构体字段名/映射 key 必须**完全一致**，包括大小写 - 即使结构体有
db:"user_name"标签，NamedExec也**不读这个标签**，只读字段名本身 - 批量插入建议用
db.MustExec()+ 占位符拼接，或引入sqlx.In()配合db.BindNamed()处理变长参数
int64 字段对应 MySQL 的 INT，只要名字对不上，就扫不到；而名字对上了，类型不兼容（比如把 string 映射到 INT）才会在运行时报错。 
