Go expvar 怎样注册自定义运行时变量

如果 Go 服务已经有健康检查和日志，但还想快速查看“已接收请求数、队列深度、构建信息”这类运行时数据，可以先用标准库 expvar。它把变量注册到一个全局表中，再通过 HTTP 以 JSON 形式提供给调试或运维工具读取。

最直接的结论是：整数、浮点数、字符串和键值表优先用 expvar.NewInt、expvar.NewFloat、expvar.NewString、expvar.NewMap；需要动态计算的对象用 expvar.Publish 注册一个实现 expvar.Var 的值。本文用一个自定义 ServeMux 把它们统一挂到 /debug/vars。

本文解决：怎样注册自定义运行时变量、怎样让它出现在 JSON 响应中、为什么同名注册会导致 panic，以及怎样把调试入口限制在合适的网络边界。

一、先分清 expvar 的三层职责

expvar 的工作可以拆成三层：变量对象负责生成合法 JSON 值，全局变量表负责按名字保存它们，HTTP Handler 负责把变量表编码成响应。只注册变量而不挂载读取入口，读者看不到结果；只挂载 Handler 而不注册自定义变量，响应里只有默认的 cmdline 和 memstats 等条目。

标准库文档说明，expvar.Publish(name, v) 会声明一个命名的导出变量；如果名称已经注册，调用会记录日志并触发 panic。因此名称规划是代码的一部分，不应把它当作请求到来后的临时操作。

二、用 NewInt 和 NewMap 注册常用指标

计数器和简单键值指标不需要自己实现 expvar.Var。NewInt 返回一个已经注册到全局变量表的整数变量，后续用 Add 或 Set 修改；NewMap 适合把多个维度放在一个变量下，例如不同队列、不同结果类型的数量。

下面的例子把注册放在包级变量初始化阶段，把更新动作留在请求处理函数中。这样启动时就能确定指标名称，业务代码只负责修改数值。

package main

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

var (
    // NewInt 会立即注册名称，后续只更新数值。
    requestsAccepted = expvar.NewInt("requests_accepted")
    // NewMap 适合把状态维度集中在一个 JSON 对象里。
    resultByKind = expvar.NewMap("result_by_kind")
)

func handle(w http.ResponseWriter, r *http.Request) {
    // 每接收一次请求就累加，避免直接读写普通 int 造成竞态。
    requestsAccepted.Add(1)
    // Map 的 Add 会在键不存在时创建一个整数变量。
    resultByKind.Add("ok", 1)
    _, _ = fmt.Fprintln(w, "accepted")
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", handle)
    // 使用自定义 mux，明确只把 expvar Handler 放在调试路径。
    mux.Handle("/debug/vars", expvar.Handler())
    _ = http.ListenAndServe(":8080", mux)
}

这个例子中，requests_accepted 会输出一个数字，result_by_kind 会输出类似 {"ok":1} 的对象。它们的更新方法由标准库负责同步，业务代码不需要自行加锁来保护这些 expvar 对象。

三、用 Publish 注册动态自定义变量

当变量不是一个适合长期保存的计数器，而是需要在读取时重新计算的快照，可以使用 expvar.Func。它满足 expvar.Var 接口，每次读取都会调用函数，并把返回值按 JSON 格式编码。

var buildInfo = expvar.Func(func() any {
    // 动态值在读取时计算，适合低频查看的版本或构建信息。
    return map[string]string{
        "go":      runtime.Version(),
        "service": "orders-api",
    }
})

func init() {
    // Publish 只负责把自定义 Var 绑定到一个全局名称。
    expvar.Publish("build_info", buildInfo)
}

实际文件需要补上 runtime 导入。如果你已经使用 NewInt 或 NewMap，不要再次用相同名称调用 Publish。同名注册不是覆盖操作，而是启动期错误，通常会让程序在初始化阶段直接退出。

四、挂载 Handler 后再读取 /debug/vars

expvar.Handler() 返回一个 http.Handler。把它挂到自定义 ServeMux 后，服务就有了一个清晰的调试入口。这里没有把整个默认路由表交给 expvar，而是只暴露一个明确的路径，便于后面接鉴权、内网监听或反向代理访问控制。

# 读取服务自己的 expvar JSON；命令只请求 GET，不修改指标。
curl --fail --silent http://127.0.0.1:8080/debug/vars

响应中应能看到 requests_accepted、result_by_kind 和 build_info 等自定义名称。这里的“应能看到”是接口设计上的预期；图示用于解释数据关系，不替代你对本地服务的实际读取。

五、名称冲突、动态计算和暴露边界

有三个边界值得在代码评审时单独确认：

• 名称必须稳定且唯一：把名称当作外部消费者依赖的字段，避免不同包在 init 中注册同名变量。
• 动态函数要轻：expvar.Func 在读取时执行，不能把慢查询、网络请求或需要长时间持锁的工作塞进其中。
• 调试入口要受控：/debug/vars 可能包含命令行参数、内存统计和业务指标。生产环境应使用内网监听、反向代理鉴权或单独的管理端口，不要把它无条件暴露到公网。

另外，expvar.Var.String 必须返回合法 JSON 值的字符串表示；如果自定义类型返回未转义的普通文本，读取端可能无法按预期解析。对于结构化结果，优先让 expvar.Func 返回可 JSON 编码的基础类型、切片或映射。

六、总结：按变量形态选择注册方式

记住这一条即可：先为变量选择稳定名称，再选择合适的 Var 实现，最后把 Handler 挂到受控的 HTTP 路径。这样自定义运行时变量既能快速接入，也不会把调试接口误当成无边界的公开 API。

常见问题

为什么 Publish 同名会 panic？

expvar 的全局变量表要求名称唯一，重复注册不是覆盖，而是程序初始化阶段的错误。为每个包加统一前缀或集中注册可以减少冲突。

NewInt 注册后还要再 Publish 吗？

不需要。NewInt、NewFloat、NewString 和 NewMap 本身已经完成注册；Publish 主要用于已有的自定义 Var。

怎样把 expvar 放到非默认路径？

用 expvar.Handler() 获取 Handler，再注册到自己的 http.ServeMux。这样可以决定具体路径和监听入口。