日志最好能被机器读懂
过去很多 Go 小项目使用标准库 log：
log.Printf("user %d login failed: %v", userID, err)
这种日志给人看没问题，但给日志系统分析不够方便。如果你想按 user_id 搜索，按 status 聚合，按 duration_ms 排序，结构化日志会更好。Go 1.21 引入了标准库 log/slog，让结构化日志成为标准能力。
slog 的核心思想很简单：日志消息是一段文本，额外上下文用 key/value 字段表示。字段稳定后，日志平台、命令行工具和开发者都更容易处理。
这篇文章从最小用法讲起，然后写一个 HTTP 请求日志中间件。
最小用法
logger := slog.Default()
logger.Info("server starting")
带字段：
logger.Info("server starting",
"addr", ":8080",
"env", "development",
)
错误：
if err != nil {
logger.Error("load config failed", "err", err)
}
字段名建议稳定、短小、英文，比如 request_id、user_id、path、status、duration_ms。不要今天写 uid，明天写 userId，后天写 user_id。日志字段不统一，后面查询会很痛苦。
TextHandler 和 JSONHandler
文本日志：
logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
logger.Info("hello", "name", "Go")
JSON 日志：
logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
logger.Info("hello", "name", "Go")
本地开发用文本更容易看，生产环境通常用 JSON，更适合日志平台解析。可以通过配置选择：
func NewLogger(format string) *slog.Logger {
if format == "json" {
return slog.New(slog.NewJSONHandler(os.Stdout, nil))
}
return slog.New(slog.NewTextHandler(os.Stdout, nil))
}
使用：
logger := NewLogger(os.Getenv("LOG_FORMAT"))
不要在业务函数里到处决定日志格式。格式是运行环境选择，业务只负责记录事件和字段。
With 添加公共字段
logger := slog.New(slog.NewJSONHandler(os.Stdout, nil)).
With("service", "user-api").
With("version", "v1.0.0")
之后这两个字段会出现在每条日志里。请求级别也可以创建子 logger：
requestLogger := logger.With(
"request_id", requestID,
"method", r.Method,
"path", r.URL.Path,
)
requestLogger.Info("request started")
With 返回新 logger，不会修改原 logger。这样你可以在不同范围添加不同字段。
HTTP 请求日志
记录状态码需要包装 ResponseWriter：
type statusRecorder struct {
http.ResponseWriter
status int
}
func (r *statusRecorder) WriteHeader(status int) {
r.status = status
r.ResponseWriter.WriteHeader(status)
}
中间件：
func RequestLogger(logger *slog.Logger, next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
rec := &statusRecorder{
ResponseWriter: w,
status: http.StatusOK,
}
next.ServeHTTP(rec, r)
logger.Info("http request",
"method", r.Method,
"path", r.URL.Path,
"status", rec.status,
"duration_ms", time.Since(start).Milliseconds(),
)
})
}
使用：
mux := http.NewServeMux()
mux.HandleFunc("/healthz", healthHandler)
server := &http.Server{
Addr: ":8080",
Handler: RequestLogger(logger, mux),
}
请求日志是最基础的可观测性。它应该告诉你：什么方法、什么路径、返回什么状态、耗时多久。
不要记录敏感信息
结构化日志更容易被收集和长期保存，所以敏感数据更要小心。不要记录密码、token、完整身份证、银行卡号和完整私密请求体。
错误示例：
logger.Info("login request",
"email", req.Email,
"password", req.Password,
)
正确示例：
logger.Info("login failed",
"email", req.Email,
"reason", "invalid_credentials",
)
是否记录 email 也要看业务合规要求。日志不是另一个数据库，不能什么都塞进去。
在业务函数里传 logger
小项目里可以直接使用全局默认 logger，但服务变大后，更推荐把 logger 作为依赖传入：
type UserService struct {
logger *slog.Logger
}
func NewUserService(logger *slog.Logger) *UserService {
return &UserService{logger: logger}
}
func (s *UserService) Register(ctx context.Context, email string) error {
s.logger.Info("register user", "email", email)
if email == "" {
return fmt.Errorf("email is required")
}
return nil
}
如果请求里有 request id，可以创建带字段的 logger：
requestLogger := logger.With("request_id", requestID)
service := NewUserService(requestLogger)
这样 service 不需要知道 request id 从哪里来，只是正常记录日志。测试时也可以传一个写到 buffer 的 logger，检查是否输出了关键字段。不要让业务函数到处调用 slog.Default()，否则依赖隐藏起来，后面替换和测试都会麻烦。
Handler 选项定制
slog.HandlerOptions 可以控制日志级别和字段替换：
handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
Level: slog.LevelInfo,
AddSource: true,
ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
if a.Key == "password" || a.Key == "token" {
return slog.Attr{}
}
return a
},
})
logger := slog.New(handler)
ReplaceAttr 是全局脱敏的好位置，比每个调用方单独处理更可靠。
常见问题 FAQ
Q: slog 和 zap/logrus 怎么选？
A: 新项目直接用 slog，零依赖且是标准库。已有 zap/logrus 的项目不必迁移，但新项目优先考虑 slog。
Q: 日志级别怎么动态调？
A: 可以用 slog.LevelVar，它是原子操作的日志级别变量：
var logLevel = new(slog.LevelVar)
logLevel.Set(slog.LevelDebug)
handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: logLevel})
运行时调用 logLevel.Set(slog.LevelWarn) 即可调整全局日志级别。
Q: 如何 rolling 日志文件？
A: slog 本身不做文件轮转。可以把 handler 的输出定向到 lumberjack 等轮转库，或直接用 systemd/docker 的日志收集。
常见陷阱
- 偶数参数方法调用：
slog.Info("msg", "key")缺 value，编译不会报错但行为不可预期。仔细检查 key/value 成对出现。 - 不过渡使用 With：每条日志都创建新 logger 会增加分配。请求级别一次
With就可以。 - 忽略 source：
AddSource: true会记录代码位置，但增加日志体积，生产环境根据需要开启。
对比表
| 方案 | 性能 | 依赖 | 结构化 | 推荐 |
|---|---|---|---|---|
| 标准库 log | 中 | 无 | 否 | 仅极简脚本 |
| slog | 中 | 无 | 是 | 新项目首选 |
| zap | 高 | 有 | 是 | 高性能场景 |
| zerolog | 很高 | 有 | 是 | 极致性能 |
小结
Go 1.21 的 log/slog 让结构化日志进入标准库。你可以选择文本或 JSON handler，用 key/value 记录字段，用 With 添加公共上下文，用中间件记录 HTTP 请求，ReplaceAttr 做全局字段替换。
好的日志不在于多，而在于关键字段清楚、命名稳定、敏感信息克制。slog.LevelVar 支持运行时调整日志级别，使运维更灵活。小服务从一开始用 slog 建立习惯，后面接日志平台会轻松很多。保持日志字段命名规范是长期投资，越早统一，后续查询和告警越高效。
真实项目用例
在实际团队协作中，下面是几个推荐的工作流：
代码审查清单
- 函数是否处理了所有 error 返回值
- 并发代码是否有明确的退出路径和 WaitGroup
- 用户输入是否经过校验和清洗
- 敏感配置是否通过环境变量或加密存储注入
- 测试是否覆盖了正常路径和至少一个错误路径
- 日志是否包含足够的上下文信息但不泄露敏感数据
- 接口设计是否符合最小接口原则
CI/CD 集成建议
- 每次提交前运行
go fmt ./... - CI 中运行
go vet ./...和golangci-lint run - 单元测试使用
go test -race ./...检测数据竞争 - 关键路径的 benchmark 加入回归测试
- 使用
go mod verify确保依赖完整性
性能调优检查点
- 使用 pprof 分析 CPU 和内存使用
- 关注 benchmark 的 allocs/op，减少高频路径的堆分配
- 检查数据库查询是否使用索引
- 确认外部 HTTP 调用有合理的超时设置
- 缓存热点数据，但注意缓存一致性和过期策略
面试高频考点
如果你正在准备 Go 相关面试，以下概念是高频考点：
- goroutine 和线程的区别
- channel 的缓冲和非缓冲用法
- defer 的执行顺序和与返回值的关系
- map 的并发不安全性和解决方案
- interface 的隐式实现和类型断言
- slice 的底层数组和 append 机制
- GC 的基本原理和调优参数
- context 的使用场景和超时控制
- error 的包装和 errors.Is/errors.As
- sync.Mutex vs sync.RWMutex vs atomic
掌握这些概念意味着你具备了独立开发 Go 服务的基础能力。继续在实际项目中磨练，你会越来越熟悉 Go 的工程风格和最佳实践。
常见问题（FAQ）
Q: 这个特性在实际项目中真的有用吗？
A: 是的。本文介绍的技术来源于真实后端开发场景。无论是标准库工具还是工程实践，在日常服务开发中都会反复用到。
Q: Go 版本会影响示例代码吗？
A: 本文代码主要针对 Go 1.20+ 编写。较新版本（如 1.22、1.23）的语法可能有微调，但核心概念保持不变。如有版本差异，文中会特别说明。
Q: 学习 Go 应该先学标准库还是直接上框架？
A: 强烈建议先学标准库。框架是对标准库的封装和扩展。只有理解了标准库的能力边界，才能正确选择和使用框架，也才能在框架出问题时快速定位。
Q: 代码里的错误处理为什么都是显式的 if err != nil？
A: 这是 Go 的设计哲学。显式错误处理让失败路径清晰可见，不会隐藏在任何 try-catch 之后。习惯了之后，你会发现这种写法实际上降低了排查错误的难度。
Q: 并发相关代码怎么测试？
A: 使用 Go 内置的 -race 标志检测数据竞争：go test -race ./...。结合 sync.WaitGroup 和 context.WithTimeout 编写有退出路径的并发测试，避免 goroutine 泄漏。
常见坑与避坑指南
- 不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
- 资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。
defer是一个好习惯。 - 不要忽略错误：即使
defer file.Close()可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。 - 不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用
sync.WaitGroup和context管理生命周期。 - 不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
- 不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。
延伸阅读与实践建议
读完本文后，建议完成以下实践：
- 把文中所有示例代码在自己的机器上跑一遍
- 给示例代码补充错误分支的测试用例
- 尝试基于本文内容构建一个小型完整项目
- 在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
- 订阅 Go 官方博客，关注语言演进和最佳实践更新
参考资源
- Go 官方网站：https://go.dev/
- Go 标准库文档：https://pkg.go.dev/std
- Go by Example：https://gobyexample.com/
- Effective Go：https://go.dev/doc/effective_go
- Go 常见问题：https://go.dev/doc/faq
- Go 项目实战社区案例和开源项目源码
本文力求在讲解技术细节的同时兼顾工程实用性。Go 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。
自定义 Handler
如果标准 TextHandler 和 JSONHandler 不满足需求，可以自定义：
type SimpleHandler struct {
out io.Writer
}
func (h *SimpleHandler) Enabled(ctx context.Context, level slog.Level) bool {
return true
}
func (h *SimpleHandler) Handle(ctx context.Context, r slog.Record) error {
fmt.Fprintf(h.out, "%s [%s] %s", r.Time.Format("2006-01-02 15:04:05"), r.Level, r.Message)
r.Attrs(func(a slog.Attr) bool {
fmt.Fprintf(h.out, " %s=%v", a.Key, a.Value)
return true
})
fmt.Fprintln(h.out)
return nil
}
func (h *SimpleHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
return h
}
func (h *SimpleHandler) WithGroup(name string) slog.Handler {
return h
}
自定义 Handler 可以控制输出格式、过滤字段、写入目标等。
日志采样
极高 QPS 下，不需要记录每条请求。可以采样：
func SampledLogger(base *slog.Logger, fraction float64) *slog.Logger {
return slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
AddSource: true,
ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
if a.Key == "sample_fraction" {
return slog.Float64("sample_fraction", fraction)
}
return a
},
}))
}
或者更简单地，只对错误日志 100% 记录，对正常请求日志按比例丢弃。
多目标日志
同时输出到文件和 stdout：
file, _ := os.OpenFile("/var/log/app.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
mw := io.MultiWriter(os.Stdout, file)
logger := slog.New(slog.NewJSONHandler(mw, nil))
结合 lumberjack.Logger 实现日志滚动：
import "gopkg.in/natefinch/lumberjack.v2"
lw := &lumberjack.Logger{
Filename: "/var/log/app.log",
MaxSize: 100, // MB
MaxBackups: 3,
MaxAge: 7, // days
Compress: true,
}
logger := slog.New(slog.NewJSONHandler(lw, nil))
多环境日志策略
| 环境 | 格式 | 级别 | 输出 |
|---|---|---|---|
| 开发 | text | debug | stdout |
| 测试 | json | info | stdout + 文件 |
| 生产 | json | warn | 文件 + 转发 |
| 预发 | json | info | stdout |
不同环境用不同日志策略，保持灵活和成本平衡。生产环境日志量巨大， Warn+ 级别能显著降低存储和处理压力。
总结
slog 是 Go 结构化日志的标准答案。从基本使用到自定义 Handler，从多目标到采样，slog 提供了足够的扩展能力。关键是先建立起结构化日志的意识，再逐步完善工程实践。
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。