日志不是程序最后随手加的一行 fmt.Println。线上排查问题时，日志经常是第一证据：哪个用户触发了请求、参数是什么、调用下游花了多久、错误发生在哪一层。纯文本日志能看，但不方便检索。结构化日志把关键信息放到字段里，日志平台可以按字段过滤、聚合和统计。
Go 标准库从 1.21 开始提供 log/slog。它不追求复杂功能，但足够覆盖大多数入门项目。
创建 JSON Logger
服务端程序通常使用 JSON 日志：
package main
import (
"log/slog"
"os"
)
func main() {
logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
logger.Info("server started", "addr", ":8080")
}
输出类似：
{"time":"2025-07-28T08:54:00+08:00","level":"INFO","msg":"server started","addr":":8080"}
字段 addr 可以被日志系统索引。以后想找某个端口的启动记录，不需要全文搜索。
字段要稳定
结构化日志最怕字段名一会儿叫 user_id，一会儿叫 uid，一会儿又叫 userId。团队要尽量统一命名。
logger.Info("order created",
"user_id", userID,
"order_id", orderID,
"amount", amount,
)
字段值也要选对类型。金额如果是分，就叫 amount_cents，不要只叫 amount 让人猜单位。耗时可以用 duration_ms，便于统计。
带上下文的 logger
一组日志共享字段时，可以用 With：
reqLogger := logger.With(
"request_id", requestID,
"user_id", userID,
)
reqLogger.Info("load profile")
reqLogger.Info("profile loaded", "duration_ms", 12)
这样每条日志都会带上 request_id 和 user_id。排查一次请求时，只要按 request_id 过滤，就能看到完整路径。
HTTP 请求日志中间件
一个简单中间件：
func accessLog(logger *slog.Logger, next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
next.ServeHTTP(w, r)
logger.Info("http request",
"method", r.Method,
"path", r.URL.Path,
"duration_ms", time.Since(start).Milliseconds(),
"remote", r.RemoteAddr,
)
})
}
这个版本还拿不到状态码，因为 http.ResponseWriter 默认不会记录。可以包一层：
type statusWriter struct {
http.ResponseWriter
status int
}
func (w *statusWriter) WriteHeader(code int) {
w.status = code
w.ResponseWriter.WriteHeader(code)
}
中间件里使用：
sw := &statusWriter{ResponseWriter: w, status: http.StatusOK}
next.ServeHTTP(sw, r)
logger.Info("http request", "status", sw.status)
这样访问日志能按状态码筛选。看到 500 增多时，可以快速定位路径。
错误日志不要重复打
新手常在每一层都打印错误：repo 打一次，service 打一次，handler 再打一次。结果同一个错误出现三条日志，排查时反而混乱。通常在边界处记录一次，比如 HTTP handler 或 worker 入口。
if err := svc.Create(ctx, req); err != nil {
logger.Error("create order failed",
"error", err,
"user_id", req.UserID,
"sku", req.SKU,
)
http.Error(w, "create order failed", http.StatusInternalServerError)
return
}
下层函数负责用 %w 包装错误，上层负责记录上下文。这样日志既有业务字段，也保留错误链。
级别怎么选
日志级别没有绝对标准，但可以有团队约定：
logger.Debug("cache miss", "key", key)
logger.Info("job finished", "job_id", id)
logger.Warn("retry third party", "attempt", attempt, "error", err)
logger.Error("job failed", "job_id", id, "error", err)
Debug 给开发和临时排查；Info 记录正常关键事件；Warn 表示出现异常但程序还能恢复；Error 表示请求或任务失败，需要关注。不要把用户输错密码记成 error，也不要把数据库写入失败记成 info。
隐私和脱敏
结构化日志很方便，也更容易把敏感信息稳定地送进日志系统。密码、token、身份证号、完整手机号不要记录。必要时只记录后四位或哈希。
func maskPhone(s string) string {
if len(s) < 4 {
return "***"
}
return "***" + s[len(s)-4:]
}
日志是排查工具，不是数据仓库。能不记录敏感字段，就不要记录。尤其是第三方回调、登录请求、支付参数，写日志前要多想一步。
设置默认 logger
如果项目里很多地方使用 slog.Info，可以设置默认 logger：
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
Level: slog.LevelInfo,
}))
slog.SetDefault(logger)
然后：
slog.Info("started")
小项目这样很方便。较大的项目里，我更倾向显式把 *slog.Logger 传给组件，依赖关系更清楚，也更容易在测试里替换。
测试日志输出
测试时可以把日志写到 buffer：
var buf bytes.Buffer
logger := slog.New(slog.NewJSONHandler(&buf, nil))
logger.Info("created", "id", 12)
if !strings.Contains(buf.String(), `"id":12`) {
t.Fatalf("missing id field: %s", buf.String())
}
通常不需要测试每条日志，但关键审计日志、任务状态日志可以测，避免重构时把重要字段改没了。
给组件注入 Logger
服务变大后，不建议每个包都直接用全局 slog.Default()。把 logger 作为依赖传进去，组件边界更清楚。
type OrderService struct {
logger *slog.Logger
repo OrderRepo
}
func NewOrderService(logger *slog.Logger, repo OrderRepo) *OrderService {
return &OrderService{logger: logger, repo: repo}
}
func (s *OrderService) Create(ctx context.Context, order Order) error {
if err := s.repo.Save(ctx, order); err != nil {
s.logger.Error("save order failed", "order_id", order.ID, "error", err)
return err
}
return nil
}
测试时可以传一个写到 io.Discard 的 logger，避免测试输出被日志淹没。线上则可以在组装依赖时统一加上服务名、版本和环境字段。
日志字段不要塞整包对象
结构化日志不是把整个请求对象都丢进去。对象里可能有密码、token、长文本，也可能让日志变得巨大。更好的做法是挑选排查需要的字段。
logger.Info("payment callback",
"payment_id", req.PaymentID,
"merchant_id", req.MerchantID,
"status", req.Status,
)
字段少而稳定，日志平台更容易建索引，排查时也更快。真正需要完整原文的回调，可以保存到受控的审计表或对象存储，而不是长期写入普通应用日志。
小结
slog 让 Go 标准库具备了结构化日志能力。入门时先做到：使用 JSON handler，字段名稳定，错误只在边界记录一次，日志级别有明确含义，敏感信息不进日志。
日志写得好，线上排查会轻很多；日志写得乱，数据越多越像噪音。结构化日志的价值不在“看起来高级”，而在于它能被检索、统计和关联。每加一个字段，都应该想清楚以后会怎样使用它。
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。