Go expvar.Handler 与默认 /debug/vars 有什么区别

expvar.Handler() 与默认的 /debug/vars 并不是两套指标系统。它们都输出 expvar 包级全局注册表中的变量，默认还包含 cmdline 和 memstats。真正的区别在入口：导入 expvar 会在 http.DefaultServeMux 上自动注册默认地址，而 Handler() 让你把同一个输出处理器显式挂到自定义 ServeMux 或非标准路径。

官方文档：https://pkg.go.dev/expvar

使用默认 mux、接受固定地址时，直接访问 GET /debug/vars 最省事；使用自定义 mux、独立管理端口、鉴权中间件或自定义路径时，使用 expvar.Handler()。后者不会创建独立变量注册表，也不会自动替你限制请求方法。

问题现场：默认地址能用，换成自定义 mux 就 404

常见现象是：程序里已经 import _ "expvar"，用 http.ListenAndServe(addr, nil) 时能打开 /debug/vars；把服务改为 http.NewServeMux() 后，业务接口正常，指标地址却返回 404。

初步判断不要放在“expvar 是否发布了变量”上，而要先看 HTTP 服务器到底使用哪个 mux。nil Handler 代表使用 http.DefaultServeMux，而 http.NewServeMux() 创建的是另一套路由表。expvar 的自动注册发生在默认 mux 上，不会同步复制到新 mux。

动手验证：两种入口读到的是同一份变量

下面用一个计数器验证共享关系。expvar.NewInt 在包级注册表发布变量；默认路由和显式 Handler 都会在响应 JSON 中看到它。示例使用自定义 mux，避免把测试结果依赖到进程中其他包注册的默认路由。

package main

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

var requests = expvar.NewInt("requests_total")

func main() {
    mux := http.NewServeMux()

    mux.HandleFunc("GET /work", func(w http.ResponseWriter, r *http.Request) {
        // Add 是原子更新；访问业务接口后，两个 expvar 入口都会读取到新值。
        requests.Add(1)
        w.WriteHeader(http.StatusNoContent)
    })

    // Handler 只负责输出全局变量；路径和 GET 方法约束由 ServeMux 模式提供。
    mux.Handle("GET /internal/vars", expvar.Handler())

    // 传入自定义 mux 后，DefaultServeMux 上自动注册的 /debug/vars 不会被这个服务使用。
    server := &http.Server{
        Addr:    "127.0.0.1:8080",
        Handler: mux,
    }
    log.Fatal(server.ListenAndServe())
}

这个程序暴露的是 GET /internal/vars。虽然导入 expvar 时仍会把默认地址注册到 http.DefaultServeMux，但当前 Server 的 Handler 是自定义 mux，所以默认路由并不会通过这个监听地址对外服务。问题由此定位为“路由表不同”，不是“指标没有发布”。

定位原因：入口不同，变量来源相同

从标准库实现看，包初始化做了三件相关的事：向默认 mux 注册 /debug/vars，发布 cmdline，发布 memstats。Handler() 返回的则是包装同一个内部输出函数的 http.Handler。输出函数遍历的仍是包级 vars，不存在“每调用一次 Handler 就新建一份指标”的行为。

这也解释了另一个误区：把同一个 expvar.Handler() 挂到两个路径，不会得到两组不同数据；它只是给同一份 JSON 输出增加两个 HTTP 入口。如果确实需要租户隔离、子系统独立注册表或不同字段集合，expvar 标准包本身没有提供实例化 Registry，需要自行编写处理器或选择支持独立注册表的指标库。

修复方案：自定义路径时把方法和访问边界一起补上

Go 官方文档说明，从 Go 1.22 起默认 /debug/vars 请求必须使用 GET。这个限制来自默认 ServeMux 注册的 GET /debug/vars 方法模式。expvar.Handler() 本体只设置 JSON Content-Type 并写出变量，没有单独检查请求方法。

因此，自定义挂载不要只写 mux.Handle("/internal/vars", expvar.Handler()) 后就假定 POST 会被拒绝。若应用使用 Go 1.22 及之后的 ServeMux 方法模式，应显式写成：

// GET 模式把方法限制放在路由层，其他方法由 ServeMux 拒绝。
mux.Handle("GET /internal/vars", expvar.Handler())

访问控制也应放在 Handler 外层。expvar 默认输出可能包含进程命令行、运行时内存统计和业务自定义变量，不适合无条件暴露到公网。最稳妥的做法是使用仅内部网络可达的管理监听；如果必须复用业务端口，则增加认证、授权和访问日志。

func requireToken(next http.Handler, expected string) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 生产环境应从安全配置加载令牌，示例只展示中间件边界。
        if r.Header.Get("Authorization") != "Bearer "+expected {
            http.Error(w, "unauthorized", http.StatusUnauthorized)
            return
        }
        next.ServeHTTP(w, r)
    })
}

// 方法限制和鉴权都位于 expvar.Handler 外层，指标输出逻辑保持不变。
mux.Handle("GET /internal/vars", requireToken(expvar.Handler(), metricsToken))

验证结果：同时检查路径、方法和 JSON 字段

修复后不要只在浏览器里看一次页面。用 httptest 可以直接验证自定义 mux：GET 能返回 JSON，POST 被方法路由拒绝，自定义变量存在。这样以后重构路由时，也能立即发现 expvar 入口丢失。

func TestExpvarRoute(t *testing.T) {
    metricName := "route_test_total"
    if expvar.Get(metricName) == nil {
        // expvar 名称不能重复注册；测试进程内只在不存在时创建。
        expvar.NewInt(metricName).Set(7)
    }

    mux := http.NewServeMux()
    mux.Handle("GET /internal/vars", expvar.Handler())

    getReq := httptest.NewRequest(http.MethodGet, "/internal/vars", nil)
    getRec := httptest.NewRecorder()
    mux.ServeHTTP(getRec, getReq)

    if getRec.Code != http.StatusOK {
        t.Fatalf("GET 状态码 = %d", getRec.Code)
    }

    var body map[string]any
    // 用 JSON 解码检查字段，不依赖输出键的文本排列顺序。
    if err := json.NewDecoder(getRec.Body).Decode(&body); err != nil {
        t.Fatalf("响应不是合法 JSON: %v", err)
    }
    if _, ok := body[metricName]; !ok {
        t.Fatalf("缺少指标 %q", metricName)
    }

    postReq := httptest.NewRequest(http.MethodPost, "/internal/vars", nil)
    postRec := httptest.NewRecorder()
    mux.ServeHTTP(postRec, postReq)

    // Go 1.22+ 的方法模式应拒绝 POST，避免自定义挂载意外放宽默认语义。
    if postRec.Code != http.StatusMethodNotAllowed {
        t.Fatalf("POST 状态码 = %d", postRec.Code)
    }
}

这段测试还避开了一个常见问题：expvar 的变量名在进程内必须唯一，重复调用 Publish 或 NewInt 注册同名变量会触发 panic。大型项目应让每个指标只在固定包的初始化位置创建一次，测试则先用 expvar.Get 判断。

常见误区速查

• 只空白导入就能在任意 mux 上访问：不对。空白导入只触发初始化，自动路由仍属于 DefaultServeMux。
• Handler 能返回一套独立指标：不对。它读取同一份全局变量注册表。
• 自定义 Handler 天然只接受 GET：不对。方法限制要由路由模式或中间件提供。
• 换路径后默认路径自动消失：不对。默认注册仍存在于 DefaultServeMux，只是你的 Server 未必使用它。
• /debug/vars 可以直接开放公网：不建议。先评估 cmdline、memstats 和业务指标是否泄露运行信息。

相关问题

只想使用默认 /debug/vars，应该怎么导入？

可以使用 import _ "expvar" 触发包初始化，并确保 HTTP Server 使用 http.DefaultServeMux。如果还要创建自定义变量，就使用普通具名导入并调用 expvar.NewInt、NewMap 等方法。

能把 Handler 挂到多个管理端口吗？

可以，但它们看到的是同一份进程级变量。更重要的是分别检查每个监听地址的网络可达性、认证和超时配置。

为什么返回 JSON 里总有 cmdline 和 memstats？

它们由 expvar 包初始化时自动发布。Handler() 不会过滤这两个变量，自定义路径也不会改变输出集合。

Handler 与 http.DefaultServeMux 有绑定关系吗？

Handler 返回的是独立的 http.Handler 值，可以挂到任意 mux；只有默认 /debug/vars 的自动注册与 DefaultServeMux 绑定。

总结

选择标准很简单：默认 mux 加固定地址，就用 GET /debug/vars；自定义 mux、非标准路径、独立管理端口或鉴权场景，就显式安装 expvar.Handler()。无论哪种入口，变量仍来自同一个全局注册表。自定义挂载时，把 GET 方法限制、访问控制和路由测试一起补齐，才能避免“地址换了，安全语义也跟着丢了”。