本文介绍通过 sql.Null* 类型定义通用结构体，使 sqlx 能安全、灵活地映射任意列组合的查询结果，避免为每个 SQL 查询重复定义结构体，同时妥善处理 NULL 值与 JSON 序列化问题。
本文介绍通过 `sql.null*` 类型定义通用结构体，使 sqlx 能安全、灵活地映射任意列组合的查询结果，避免为每个 sql 查询重复定义结构体，同时妥善处理 null 值与 json 序列化问题。
在使用 jmoiron/sqlx 进行 PostgreSQL 查询时，若需支持多种动态 SELECT 语句（如 SELECT a,b,c FROM table_a 和 SELECT x,y,z FROM table_b），传统做法是为每种字段组合单独定义结构体（如 Resp1、Resp2），不仅冗余，还难以维护。幸运的是，sqlx 支持按列名自动绑定，只要结构体字段名（或 db 标签）与查询返回的列名匹配，即可完成映射——而无需所有字段都出现在查询中。
核心解决方案是：*定义一个涵盖所有可能字段的“超集结构体”，并统一使用 `sql.Null类型（如sql.NullString、sql.NullInt64、sql.NullFloat64`）**。这样既能兼容任意子集查询，又能正确处理数据库中的 NULL 值。
✅ 推荐结构体定义方式
import (
"database/sql"
"time"
)
type CommonRow struct {
A sql.NullString `db:"a" json:"a,omitempty"`
B sql.NullString `db:"b" json:"b,omitempty"`
C sql.NullString `db:"c" json:"c,omitempty"`
D sql.NullInt64 `db:"d" json:"d,omitempty"`
E sql.NullFloat64 `db:"e" json:"e,omitempty"`
F sql.NullTime `db:"f" json:"f,omitempty"`
}- db:"xxx" 标签确保 sqlx 按列名（而非字段名顺序）绑定；
- 所有字段均为 sql.Null* 类型，可安全接收 NULL 或非 NULL 值；
- json:",omitempty" 配合自定义 JSON marshaling 可隐藏空值（见下文）。
✅ 使用示例
var rows []CommonRow
// 查询仅包含 a, b, c 的记录
err := db.Select(&rows, "SELECT a, b, c FROM users WHERE active = $1", true)
if err != nil {
log.Fatal(err)
}
// 此时 D/E/F 字段的 Valid=false，Value 为零值，不会参与 JSON 输出（经优化后）
// 查询仅包含 d, e 的记录
err = db.Select(&rows, "SELECT d, e FROM stats WHERE period = $1", "2024Q1")
if err != nil {
log.Fatal(err)
}
// 此时 A/B/C/F 字段保持 Valid=false，完全无影响⚠️ 注意事项与进阶优化
-
JSON 序列化中的 Valid 字段问题
默认 sql.NullString 序列化为 {"String":"value","Valid":true}，通常不符合 API 需求。推荐为结构体实现自定义 MarshalJSON 方法，或使用封装类型：// 简洁版：为 CommonRow 添加方法 func (r CommonRow) MarshalJSON() ([]byte, error) { type Alias CommonRow // 防止递归 return json.Marshal(&struct { A *string `json:"a,omitempty"` B *string `json:"b,omitempty"` C *string `json:"c,omitempty"` D *int64 `json:"d,omitempty"` E *float64 `json:"e,omitempty"` F *time.Time `json:"f,omitempty"` }{ A: r.A.String, B: r.B.String, C: r.C.String, D: r.D.Int64, E: r.E.Float64, F: r.F.Time, }) } 性能考量
sql.Null* 类型开销极小，且避免了反射动态构建结构体的复杂性与运行时风险，是官方推荐的 NULL 安全方案。字段命名一致性
确保数据库列名（如 user_name）与结构体 db 标签（db:"user_name"）严格一致；若列名为驼峰（如 userName），可通过 db.MapperFunc() 自定义映射逻辑。扩展性提示
若字段数量庞大或存在多组逻辑组合，可考虑将 CommonRow 拆分为多个领域内“宽表结构体”（如 UserCommon、StatsCommon），兼顾可读性与复用性。
综上，借助 sql.Null* + 显式 db 标签 + 自定义 JSON 序列化，你可在 sqlx 中优雅实现“一套结构体适配多类查询”的目标，兼顾安全性、简洁性与工程可维护性。
