zap 默认不记录sql结构化字段，因其是通用日志库，不感知数据库语义；需手动注入query、args、duration_ms、rows_affected等字段，并注意敏感信息过滤、字段命名规范及sync()调用时机。
为什么 zap 默认不记录 sql 查询的结构化字段
zap 本身是通用日志库，不感知数据库或 orm 层。它不会自动提取 select、where、args 等语义信息——这些必须由你显式传入。常见错误是直接把原始 sql 字符串塞进 logger.info()，结果日志里只有 "query": "select * from users where id = ?"，丢失参数值、执行耗时、影响行数等关键上下文。
真正有用的结构化查询日志，需要你在执行 SQL 的那一刻，主动构造带语义的字段：
-
query：标准化后的 SQL（如去除换行、统一空格） -
args：参数列表（注意避免记录敏感字段，如密码、token） -
duration_ms：纳秒级耗时转毫秒，用float64(time.Since(start).Seconds() * 1000)或更准的float64(time.Since(start).Milliseconds()) -
rows_affected：对Exec/Update类操作，从sql.Result.RowsAffected()获取 -
error：仅当出错时添加，避免在Info级别打"error": null
如何给 database/sql 添加 Zap 日志拦截器
Go 标准库 database/sql 没有原生钩子，但你可以封装 sql.DB 并重写 Query、Exec 等方法。不要用全局 logger，而是把 *zap.Logger 作为字段注入：
type LoggingDB struct {
*sql.DB
logger *zap.Logger
}
<p>func (l <em>LoggingDB) Query(query string, args ...interface{}) (</em>sql.Rows, error) {
start := time.Now()
rows, err := l.DB.Query(query, args...)
fields := []zap.Field{
zap.String("query", normalizeSQL(query)),
zap.Duration("duration", time.Since(start)),
zap.Int("args_count", len(args)),
}
if err != nil {
fields = append(fields, zap.Error(err))
l.logger.Warn("db_query_failed", fields...)
} else {
l.logger.Info("db_query_executed", fields...)
}
return rows, err
}</p>
注意：normalizeSQL 建议用正则替换多余空白（regexp.MustCompile(`\s+`).ReplaceAllString(query, " ")），避免因格式差异导致日志聚合困难；args 不建议直接打到日志（可能含敏感数据），如需调试可加开关控制是否记录 zap.Any("args_redacted", len(args) > 0)。
使用 sqlx 或 gorm 时怎么接入 Zap
sqlx 没有内置日志接口，但提供 Queryx、Get 等扩展方法，仍需自己包装。重点是别漏掉 NamedQuery 和 BindStruct 场景——它们会生成动态 SQL，参数来源更隐蔽。
gorm v2+ 支持 logger.Interface，可桥接到 Zap：
db, _ := gorm.Open(mysql.Open(dsn), &gorm.Config{
Logger: logger.New(
zapadapter.NewLogger(zap.L()), // 需要 github.com/go-gorm/zapadapter
logger.Config{
SlowThreshold: time.Second,
LogLevel: logger.Info,
},
),
})
但注意：zapadapter 输出的是字符串日志，不是结构化字段。若要结构化，得自己实现 logger.Interface，在 Trace 方法里调用 zapLogger.Info("gorm_query", ...)，并手动解析 ctx 中的 gorm.io/gorm/logger.Context 提取 SQL、Rows、Error 等。
常见坑：gorm 的 Debug().First() 会触发两次日志（预编译 + 执行），容易重复记录；Preload 关联查询的日志字段名和主表混在一起，建议加 zap.String("scope", "preload") 区分。
结构化字段命名要不要统一？怎么避免被日志平台截断
字段名最好遵循内部约定，比如一律小写下划线：query_text、exec_duration_ms、affected_rows。别用 Query、DurationMs 这类驼峰，部分日志系统（如 Loki、Datadog）对大小写敏感或自动转小写，导致聚合失败。
长 SQL 容易触发日志平台单字段长度限制（如 Loki 默认 10KB）。不要无脑 zap.String("query", sql)，而应：
- 超过 500 字符时用
zap.String("query_truncated", sql[:500]+"...")+zap.Int("query_length", len(sql)) - 对
INSERT INTO ... VALUES (...)类语句，可提取表名：zap.String("table", parseTableFromSQL(sql)) - 禁止在日志中记录
password、token、api_key等关键词对应的参数值，哪怕只是调试——过滤逻辑必须在打日志前做，而不是靠日志系统脱敏
最常被忽略的一点：Zap 的 Sync() 调用时机。如果用异步 logger（zap.NewProduction() 默认就是），日志写入是后台 goroutine 完成的，进程退出时可能丢失最后几条。查慢查询时发现“明明执行了却没日志”，大概率是这个原因——加个 defer zap.L().Sync() 在 main 函数末尾。
