Go expvar怎样暴露可读取的运行指标怎样完成一个可复用的最小示例

如果你想在 Go 服务里先暴露一个简单、可读取的运行指标，标准库 expvar 已经提供了注册变量和 HTTP 输出能力。最小做法是用 expvar.NewInt 创建计数器，在业务事件发生时调用 Add，再通过默认的 /debug/vars 或自定义的 expvar.Handler 读取 JSON。

官方地址：https://pkg.go.dev/expvar

先确认指标到底从哪里出来

expvar 包会提供一个标准的公开变量接口，并通过 HTTP 在 /debug/vars 输出 JSON。它还会登记命令行参数和运行时内存统计等默认变量；如果只想让包完成注册，也可以使用副作用导入。但业务指标仍然需要自己创建并更新。

这里有一个容易忽略的边界：expvar 负责“变量如何被读取”，不负责替你决定谁可以访问、多久采集一次或如何长期存储。它适合轻量诊断、内部探针和开发阶段的运行观测；正式监控还需要在网关、网络隔离或采集系统侧补上访问控制与保留策略。

用一个计数器把业务事件变成公开变量

下面的例子把一次请求视为一个业务事件。计数器在包级创建一次，业务处理函数只负责递增；这样变量名称、更新位置和后续读取入口都比较稳定。

package main

import (
	"expvar"
	"fmt"
	"net/http"
)

var requestCounter = expvar.NewInt("demo_requests_total")

func handleWork(w http.ResponseWriter, r *http.Request) {
	// 只统计已经进入业务处理函数的请求，指标含义要和命名保持一致。
	requestCounter.Add(1)
	fmt.Fprintln(w, "ok")
}

func main() {
	http.HandleFunc("/work", handleWork)
	// 默认 ServeMux 会由 expvar 包提供 /debug/vars 入口。
	if err := http.ListenAndServe(":8080", nil); err != nil {
		// 监听失败时直接结束，避免服务看似启动但没有可用端口。
		panic(err)
	}
}

这个程序中，NewInt 已经完成命名和注册，Add 适合多个请求并发更新。不要在每个请求里重复调用同名的 NewInt 或 Publish；同一个公开名称重复登记会触发日志 panic，通常应当把指标定义放在包级变量或初始化阶段。

用独立 Handler 控制指标入口

如果服务已经有自己的路由装配方式，可以直接取出 expvar.Handler()，挂到独立的 http.ServeMux。这样不会因为为了指标而把整套业务路由都交给默认 mux，也方便后续在反向代理或内网监听器上单独限制访问。

package main

import (
	"expvar"
	"net/http"
)

func newMetricsMux() *http.ServeMux {
	mux := http.NewServeMux()
	// 只把 expvar 的 Handler 绑定到指标 mux，便于单独接入受控入口。
	mux.Handle("/debug/vars", expvar.Handler())
	return mux
}

func main() {
	metricsMux := newMetricsMux()
	// 指标服务使用独立监听地址，业务服务的路由不会自动暴露在这里。
	if err := http.ListenAndServe("127.0.0.1:8081", metricsMux); err != nil {
		// 监听失败必须显式记录或返回，不能把错误静默吞掉。
		panic(err)
	}
}

独立 Handler 只解决“路由挂在哪里”的问题，不等于访问控制。若指标监听地址可被不可信网络访问，仍要在网络层、反向代理或认证中间件处做隔离。对于只在本机采集的场景，绑定回环地址是一个明确的部署选择。

读取 JSON 时怎样判断注册是否生效

用 GET 请求读取入口即可。下面的命令是读取动作，不是程序代码，因此不在输出中混入伪造的运行结果。

# 使用 GET 读取默认 expvar 入口；响应应是 JSON 对象。
curl --silent --show-error "http://127.0.0.1:8080/debug/vars"

# 只筛选自定义计数器，便于确认名称是否已注册。
curl --silent --show-error "http://127.0.0.1:8080/debug/vars" | grep 'demo_requests_total'

排查时按三个边界判断：请求返回 404，先看是否把 Handler 挂到了正确的 mux；能打开入口但没有自定义名称，检查指标是否在请求前完成创建；启动阶段直接 panic，则优先检查是否有两个包用同一个名称重复注册。Go 1.22 起，/debug/vars 请求必须使用 GET，不能把旧的 POST 读取方式混进排查脚本。

几个边界问题

能不能把所有业务明细都塞进 expvar？

不建议。公开变量应保持低基数和明确含义，适合计数、简单状态和有限集合；把用户 ID、请求参数等高基数数据持续写入指标，会让接口内容膨胀，也会把隐私和访问风险带进观测入口。

为什么不用自己拼 JSON？

expvar.Int、Float、String 和 Map 已经实现了 Var 接口。优先使用这些类型或实现正确 JSON 字符串的自定义变量，避免手工拼接造成转义和并发问题。

什么时候应该换成更完整的监控方案？

当你需要标签维度、直方图、告警规则、采样聚合、长期存储或跨实例对比时，expvar 往往只是起点。可以保留少量低成本诊断指标，同时把正式监控交给专门的采集与存储体系。

总结

可复用的最小方案就是：在初始化阶段用 NewInt 注册一个含义明确的变量，在业务边界调用 Add，用默认 mux 或独立的 expvar.Handler 暴露 /debug/vars，最后用 GET 检查名称和数值。遇到异常时，先按“路由、注册、更新语义”三个边界拆开看，通常比直接改采集脚本更快定位。