Go expvar 入门：给小服务加几个轻量指标

很多小服务一开始没有完整监控系统，但也需要知道一些基本状态：请求数、错误数、队列长度、缓存命中次数。Go 标准库里的 可以用很低成本暴露 JSON 指标。它不替代 Prometheus 这类监控体系，但很适合入门理解“服务应该给外界看哪些状态”。

PlumePHP 9 分钟阅读 4500 字

很多小服务一开始没有完整监控系统，但也需要知道一些基本状态：请求数、错误数、队列长度、缓存命中次数。Go 标准库里的 expvar 可以用很低成本暴露 JSON 指标。它不替代 Prometheus 这类监控体系，但很适合入门理解“服务应该给外界看哪些状态”。

expvar 默认通过 /debug/vars 暴露变量。只要导入并注册变量，就能看到 JSON。

最小示例

var requestCount = expvar.NewInt("requests_total")

func handler(w http.ResponseWriter, r *http.Request) {
	requestCount.Add(1)
	fmt.Fprintln(w, "ok")
}

如果你的程序使用默认 mux，并导入了 net/http/pprof 或使用 expvar，访问 /debug/vars 可以看到：

{
  "requests_total": 12
}

实际服务中，建议把 debug 路由挂在内部端口或加认证，不要随便暴露到公网。

请求和错误计数

var (
	requestsTotal = expvar.NewInt("http_requests_total")
	errorsTotal   = expvar.NewInt("http_errors_total")
)

func MetricsMiddleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		requestsTotal.Add(1)
		rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
		next.ServeHTTP(rec, r)
		if rec.status >= 500 {
			errorsTotal.Add(1)
		}
	})
}

type statusRecorder struct {
	http.ResponseWriter
	status int
}

func (r *statusRecorder) WriteHeader(status int) {
	r.status = status
	r.ResponseWriter.WriteHeader(status)
}

这段中间件记录请求总数和 5xx 错误数。指标不需要非常复杂，能回答关键问题就有价值：服务有没有流量？错误有没有增加？

队列长度

后台任务队列可以暴露长度：

var queueLength = expvar.NewInt("jobs_queue_length")

func enqueue(job Job) {
	queueLength.Add(1)
	jobs <- job
}

func worker() {
	for job := range jobs {
		queueLength.Add(-1)
		process(job)
	}
}

如果队列长度持续增加，说明消费速度跟不上生产速度。没有这个指标时，你可能只看到任务延迟变长，却不知道积压从什么时候开始。

自定义 JSON 指标

expvar.Func 可以动态生成值：

var startedAt = time.Now()

func init() {
	expvar.Publish("uptime_seconds", expvar.Func(func() any {
		return int(time.Since(startedAt).Seconds())
	}))
}

也可以返回结构：

expvar.Publish("build_info", expvar.Func(func() any {
	return map[string]string{
		"version": version.Version,
		"commit":  version.Commit,
	}
}))

注意不要在 expvar.Func 里做慢操作。它会在请求 /debug/vars 时执行，应该只读内存状态，不要查数据库或调用外部 API。

安全边界

/debug/vars 可能暴露 Go 运行时信息、变量名和业务状态。它应该放在内部网络、管理端口或认证后面。不要把用户隐私、token、数据库地址放进 expvar。指标是给机器和运维看的，不是配置转储。

可以单独启动内部服务：

go func() {
	mux := http.NewServeMux()
	mux.Handle("/debug/vars", expvar.Handler())
	log.Println(http.ListenAndServe("127.0.0.1:9090", mux))
}()

绑定 127.0.0.1 比直接挂公网主 mux 更稳。

测试指标中间件

全局 expvar 不太适合大量单元测试，因为变量名全局唯一。更好的方式是把计数器抽象成接口，或者对中间件逻辑测状态 recorder。入门阶段至少要知道：全局指标会影响测试隔离，不要在很多测试里重复注册同名变量。

如果只是手动验证，可以运行服务后访问：

curl http://127.0.0.1:9090/debug/vars

观察请求数是否变化。

指标命名要稳定

指标名一旦被脚本、仪表盘或告警引用，就不要随便改。建议使用清楚的英文名，比如：

http_requests_total
http_errors_total
jobs_queue_length
cache_hits_total

计数器通常用 _total 结尾，当前状态用普通名。即使 expvar 没有强制规范，保持命名习惯也能降低后续迁移到 Prometheus 等系统的成本。

不要在指标里放高基数字段

expvar 的变量是全局暴露的，不适合为每个用户、每个订单、每个 URL 都创建一个变量。比如 user_123_requests 这类指标会让变量数量爆炸。小服务里指标应该少而关键：总请求、错误、队列长度、缓存命中、构建信息。需要高维度分析时，应该引入更合适的监控系统。

指标不是日志。日志记录事件，指标记录趋势。把这两个概念分清，观测体系会更干净。

给缓存加命中指标

一个常见实用指标是缓存命中和未命中：

var (
	cacheHits   = expvar.NewInt("cache_hits_total")
	cacheMisses = expvar.NewInt("cache_misses_total")
)

func (s *Service) GetConfig(ctx context.Context, key string) (Config, error) {
	if cfg, ok := s.cache.Get(key); ok {
		cacheHits.Add(1)
		return cfg, nil
	}
	cacheMisses.Add(1)
	cfg, err := s.store.Load(ctx, key)
	if err != nil {
		return Config{}, err
	}
	s.cache.Set(key, cfg)
	return cfg, nil
}

命中率能帮助你判断缓存是否真的有效。如果 miss 一直很高，可能 TTL 太短、key 设计不稳定，或者缓存根本没有覆盖热点路径。没有指标时，你只能凭感觉讨论缓存效果。

用 expvar 做临时排查

有时你还没来得及接完整监控，只想临时确认某个状态。expvar 很适合作为过渡工具。但临时指标也要有退出计划：问题排查完后，要么转成正式指标，要么删除。否则几年后 /debug/vars 里会堆满没人理解的变量。

保持指标少而明确，比堆很多“也许有用”的数字更好。

常见问题 FAQ

Q: expvar 和 Prometheus client 冲突吗？
A: 不冲突，可以同时使用。expvar 适合"先看到点什么"的过渡阶段，Prometheus 适合正式监控体系。保持指标名风格一致，方便后续迁移。

Q: 为什么变量值和实际数量不一致？
A: expvar 是进程内指标，多实例部署时每个进程有独立值。如果需要聚合，要在采集端汇总，或者使用外部时序数据库。

Q: 指标太多会影响性能吗？
A: 少量整数操作影响极小。但如果每次请求都创建新变量，map 查找和 JSON 序列化会有累积开销。控制变量数量，避免高基数。

常见陷阱

  1. 全局变量测试污染：单元测试时不要直接注册同名变量。用接口包装可解耦测试。
  2. 指标值只增不减：计数器不是当前值，是累计值。要看实时情况需要计算差值或速率。
  3. 忘了启动内部端口：把 /debug/vars 挂在公网主路由上，可能暴露过多信息。

对比表

方案复杂度持久化告警适用阶段
expvar低无无起步、调试
Prometheus中有有生产监控
StatsD低外部外部已有 StatsD 基础设施
日志 + 聚合中有需定制已有日志平台

性能提示

  1. Add 是原子操作，但频繁调用仍会影响 cache line。超高频场景可考虑每批累加到本地变量再批量 Add。
  2. /debug/vars 的 JSON 输出量随变量数增长，给外部抓取时不要放太多自定义指标。
  3. expvar.Func 里只做内存读操作，不要查数据库或做复杂计算。

小结

expvar 是 Go 标准库提供的轻量指标工具，适合暴露请求数、错误数、队列长度、启动时间和构建信息。它简单、零依赖，但也有边界：全局变量、JSON 输出、没有复杂标签模型。配合内部端口和访问控制，可以安全地用于过渡阶段。

小服务可以先用 expvar 建立观测意识。等指标维度和告警需求变复杂，再接入更完整的监控系统。先知道服务内部发生了什么，比一开始追求完整平台更重要。指标名保持稳定、命名清晰，方便后续平滑迁移到正式监控系统。

多实例部署下的指标聚合

expvar 是进程级指标。多实例部署时需要额外收集：

// 每个进程暴露指标，Prometheus 或自定义采集器汇总
func PublishInstanceMetrics(instanceID string) {
    expvar.Publish("instance_id", expvar.Func(func() any {
        return instanceID
    }))
}

采集侧区分 instance 标签后，就能看到每个实例的状态。

指标命名规范

建议的命名模式：

<模块>_<子系统>_<指标名>_<单位>
例如：
http_requests_total
http_request_duration_seconds
cache_hits_total

遵循 Prometheus 命名惯例能让后续迁移更平滑。

边界注意事项

  1. 指标值不要过大，避免 int64 溢出。
  2. 不要在 expvar.Func 中做数据库查询或 HTTP 调用。
  3. 不要记录用户个人信息到指标中。
  4. 调试路由不要暴露到公网。

expvar 入门简单，但使用时要注意安全边界和性能影响。作为起步指标工具非常合适，等需求增长后再平滑过渡到 Prometheus 等成熟方案。

实战：接口延迟统计

除了计数器，还可以用 expvar.Func 做延迟统计：

type DurationStats struct {
    mu      sync.Mutex
    total   time.Duration
    count   int64
    max     time.Duration
}

func (s *DurationStats) Record(d time.Duration) {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.total += d
    s.count++
    if d > s.max {
        s.max = d
    }
}

func (s *DurationStats) Avg() time.Duration {
    s.mu.Lock()
    defer s.mu.Unlock()
    if s.count == 0 {
        return 0
    }
    return s.total / time.Duration(s.count)
}

注册到 expvar：

var requestDuration = &DurationStats{}

func init() {
    expvar.Publish("request_duration", expvar.Func(func() any {
        return map[string]any{
            "avg_ms": requestDuration.Avg().Milliseconds(),
            "max_ms": requestDuration.max.Milliseconds(),
            "count":  requestDuration.count,
        }
    }))
}

中间件中使用：

func DurationMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        next.ServeHTTP(w, r)
        requestDuration.Record(time.Since(start))
    })
}

指标采集周期

生产环境 metrics 采集频率一般 10-30 秒一次。太频繁会增加系统负载，太稀疏会丢失峰值。配合 Grafana 等工具可以展示趋势和告警。如果只用命令行 curl /debug/vars，建议把它写成脚本，由 cron 每分钟执行并保存到文件，后续再做分析。

生产迁移建议

当 expvar 不够用时，迁移到 Prometheus 的路径通常是：

  1. 用 Prometheus client 定义同名的 Counter/Gauge。
  2. 替换 expvar.Add 为 prometheus.Inc/Add。
  3. 增加新的 histogram/summary 维度。
  4. 保留 expvar 作为 debug 入口，或完全替换。

保持指标名一致是降低迁移成本的关键。从 expvar 起步的好处是：先有了"指标意识"，知道要观测什么，再接正式系统时更有方向感。

真实项目用例

在实际团队协作中，下面是几个推荐的工作流：

代码审查清单

  • 函数是否处理了所有 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 相关面试，以下概念是高频考点：

  1. goroutine 和线程的区别
  2. channel 的缓冲和非缓冲用法
  3. defer 的执行顺序和与返回值的关系
  4. map 的并发不安全性和解决方案
  5. interface 的隐式实现和类型断言
  6. slice 的底层数组和 append 机制
  7. GC 的基本原理和调优参数
  8. context 的使用场景和超时控制
  9. error 的包装和 errors.Is/errors.As
  10. 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 泄漏。

常见坑与避坑指南

  1. 不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
  2. 资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。defer 是一个好习惯。
  3. 不要忽略错误：即使 defer file.Close() 可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。
  4. 不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用 sync.WaitGroup 和 context 管理生命周期。
  5. 不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
  6. 不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。

延伸阅读与实践建议

读完本文后，建议完成以下实践：

  1. 把文中所有示例代码在自己的机器上跑一遍
  2. 给示例代码补充错误分支的测试用例
  3. 尝试基于本文内容构建一个小型完整项目
  4. 在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
  5. 订阅 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 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。

从 expvar 到 Prometheus 的最佳迁移实践

expvar 是理解指标概念的良好起点，但它的表达能力有限。当团队需要更复杂的告警、聚合和可视化时，Prometheus 是更自然的选择。迁移路径可以是逐步的：先在关键路径上引入 Prometheus counter 和 histogram，保留 expvar 用于 debug 端口，然后在新功能中全面使用 Prometheus，最后逐步清理旧的 expvar 指标。指标命名要保持一致，比如 expvar 中的 http_requests_total 和 Prometheus 中的同名 counter，能让运维团队无缝对接。另外，在 Grafana 中创建 dashboard 时，把 expvar 和 Prometheus 的数据源放在一起，便于对比和过渡期的调试。不要一次性全部替换，平滑迁移才是工程化的做法。

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页