Go expvar.Publish 如何注册运行时指标：变量类型、并发读取与 debug/vars 输出

服务刚上线时，最容易缺的不是日志，而是一个能回答“请求到底进来了多少次”的小信号。Go 标准库的 expvar 可以把这类运行时变量以 JSON 暴露在 /debug/vars，但它不是一套完整监控系统：注册名冲突会直接触发 panic，业务端点也不该顺手把调试入口暴露到公网。

expvar 解决的是哪一类现场问题

假设一个 Go HTTP 服务已经有访问日志，但排查“偶发变慢”时仍缺少两个数字：进程启动后累计处理了多少请求，以及当前版本是否真的注册了新指标。每次为这个问题加一条临时日志，既容易被采样丢掉，也会把文本解析工作推给运维。

expvar 的思路很窄也很实用：变量注册到全局公开表，标准处理器再把这张表编码成 JSON。包初始化时还会放入 cmdline 和 memstats。它适合调试、轻量运行状态和内部探针，不适合替代带标签、聚合和告警规则的指标系统。

把请求计数接到 /debug/vars

先定义一个包级计数器，并在初始化阶段注册名称。真正处理请求时只做一次原子加法，读取侧则通过 HTTP 处理器拿到 JSON。

package main

import (
    "expvar"
    "net/http"
)

var requests = expvar.NewInt("requests")

func handler(w http.ResponseWriter, r *http.Request) {
    requests.Add(1)
    w.WriteHeader(http.StatusNoContent)
}

func main() {
    http.HandleFunc("/health", handler)
    http.ListenAndServe(":8080", nil)
}

这段代码中，请求处理先更新 requests，再由默认的 expvar HTTP 处理器响应 /debug/vars。如果服务使用自定义 http.ServeMux，可以显式注册 mux.Handle("/debug/vars", expvar.Handler())，这样调试入口的路由归属更清楚。

验收时用 curl -s http://127.0.0.1:8080/debug/vars，应该能在返回 JSON 中看到 requests。如果拿不到，先检查服务是否真的导入了 expvar、路由是否被自定义 mux 覆盖，以及请求是否走到了 handler。

选择 Int、String 还是自定义 Var

NewInt、NewFloat、NewString 和 NewMap 已经覆盖了不少运行时状态。计数器用 Int.Add，当前值用 Set；不要为了省一个变量，把“成功数”和“失败数”拼成一段字符串，否则探针侧还要重新解析。

如果指标需要动态计算，可以实现 expvar.Var。它只有一个关键约束：String 必须返回合法 JSON 值。下面的函数变量每次被读取时才计算，但它仍然应该保持快速、无副作用，不能在探针请求里做数据库全表扫描。

var queueDepth = expvar.Func(func() any {
    return queue.Len()
})

func init() {
    expvar.Publish("queue_depth", queueDepth)
}

初始化注册适合固定的包内指标；如果名称来自配置或租户输入，就不要直接传给 Publish。名称一旦重复，注册动作会触发日志 panic，动态输入还会让输出协议失去稳定性。

并发读取时，哪些状态可以相信

expvar.Do 遍历公开变量时会锁住变量表，但已有变量仍可能被并发更新。因此它保证的是“注册表遍历过程不会与新增/删除混乱”，不是所有指标在同一瞬间组成一个全局快照。

expvar.Do(func(kv expvar.KeyValue) {
    log.Printf("%s=%s", kv.Key, kv.Value.String())
})

默认 HTTP 输出同样要按单变量理解。比如 requests 和 errors 在两个并发请求之间可能分别变化，用它们计算错误率时应接受轻微时间差，或者由更专业的采集系统完成同一采样周期内的聚合。实际验收请求写成 GET /debug/vars，即可把读取方法和路径一起核对。

把调试入口放到正确的边界

Go 1.22 起，/debug/vars 请求必须使用 GET。入口本身没有替你做鉴权，也不应该把它和公网业务端口混在一起。比较稳妥的做法是让业务 mux 只处理业务路径，再用独立的内部监听器挂载 expvar.Handler()，由网络策略或反向代理限制访问。

还要注意输出内容：默认变量包含命令行和内存统计信息，命令行可能带有启动参数。不要把访问日志、密码、连接串或用户输入直接放入 expvar.String；指标名也尽量采用固定小写下划线格式，例如 queue_depth，避免版本升级时出现两套近似名称。

常见问题

expvar.Publish 和 NewInt 有什么区别？

NewInt 会创建并注册一个整数变量并返回指针；Publish 用于把自定义的 expvar.Var 放进公开表，两者都必须遵守名称唯一约束。

expvar.Int.Add 能保证多个字段一起更新吗？

不能。它只保证这个整数变量自身的更新语义。多个变量之间的业务不变量需要额外的锁、单一状态对象或更适合的指标采集方案。

为什么 curl 用 POST 访问 /debug/vars 会失败？

从 Go 1.22 起该请求必须使用 GET。先确认请求方法，再确认路径是否挂载在默认 mux 或显式注册的 expvar.Handler() 上。

上线前留下四个检查点

先用固定名称注册，再用最小的 Int 或 Func 验证 JSON 输出；随后并发请求几次，确认计数变化符合预期。最后检查 /debug/vars 是否只在内网可达，以及指标值里没有凭据和个人数据。做到这四步，expvar 就能保持它应有的轻量边界：给排障一个快速、可读、低成本的运行时窗口。