Go expvar 怎样暴露只读的运行指标

如果你想给采集端提供运行指标，又不希望它通过 HTTP 修改应用状态，expvar 可以直接完成这件事。关键是理解“只读”的边界：/debug/vars 是读取接口，客户端使用 GET 获取 JSON；指标在进程内部仍可能由代码更新。要让指标值在读取时生成，优先使用 expvar.Func，再用 expvar.Handler() 挂到明确的只读路由。

本文使用 Go 标准库的 expvar，只讨论自定义运行指标的暴露方式，不把它当作完整的监控采集系统。

只读到底限制了哪一层

expvar 默认提供 /debug/vars，返回公开变量的 JSON。当前 Go 文档明确说明该入口应使用 GET。这个约束保护的是 HTTP 入口：采集端只能读取，不能通过请求体提交新的指标值。

但 expvar.Int、expvar.Float、expvar.String 仍然提供 Set 或 Add 等方法，应用代码可以在请求处理、任务循环里更新它们。因此，“只读指标”通常有两种含义：

• 对外只开放 GET，采集端没有写入口；
• 指标值由读取时计算，应用内部也不保存一个可被随意改写的共享变量。

第二种更接近本文的目标，适合读取当前配置摘要、队列长度快照或运行状态计数。

用 expvar.Func 发布读取时计算的指标

expvar.Func 是一个函数类型，它实现了 expvar.Var。每次 expvar 需要序列化该变量时，函数都会返回当前值。返回结构体比拼接 JSON 字符串更稳妥，因为 expvar.Func.String 会负责 JSON 编码。

package main

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

func main() {
    // 每次读取时重新生成快照，外部只能通过 GET 看到结果。
    expvar.Publish("service_snapshot", expvar.Func(func() any {
        return struct {
            Ready       bool   `json:"ready"`
            Uptime      string `json:"uptime"`
            ActiveTasks int    `json:"active_tasks"`
        }{
            Ready:       true,
            Uptime:      time.Since(startTime).Round(time.Second).String(),
            ActiveTasks: currentTaskCount(),
        }
    }))

    // 标准库会把默认 expvar Handler 注册到 /debug/vars。
    if err := http.ListenAndServe(":8080", nil); err != nil {
        // 监听失败时立即退出，避免服务看似启动但没有指标入口。
        panic(err)
    }
}

var startTime = time.Now()

func currentTaskCount() int {
    // 示例返回当前快照；实际项目应读取受保护的状态或原子计数。
    return 3
}

这个例子把指标值的生成放在读取时，但 currentTaskCount 必须足够快，也不能把密码、Token、用户明细或大对象直接返回。若读取函数访问共享状态，应使用原子变量、锁或其他明确的并发保护。

用 Handler 把观察入口放进独立路由

默认注册方式适合简单服务。如果业务程序已经有自己的路由，使用 expvar.Handler() 可以把入口显式挂到独立的 ServeMux。下面的路由只接受 GET，业务处理器仍放在另一组路径中。

func metricsServer() *http.Server {
    mux := http.NewServeMux()

    // 只把 expvar Handler 放到观察路由，不复用业务路由组。
    mux.Handle("GET /debug/vars", expvar.Handler())
    mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) {
        // 健康检查只返回状态，不把业务数据混进指标响应。
        w.WriteHeader(http.StatusNoContent)
    })

    return &http.Server{
        Addr:    ":9090",
        Handler: mux,
    }
}

这里的“只读”来自路由方法约束和 Handler 的返回语义：采集端访问 GET /debug/vars，应用没有提供更新指标的 HTTP 动作。若服务对外开放，仍应在网络层或鉴权层限制该端口，不能因为它是 GET 就把所有内部状态暴露给公网。

三个容易踩到的边界

1. 不要把“只读”理解成“永远不变”。 Func 的结果可以随时间变化；只要请求方不能写入，它仍然是只读观察接口。
2. 名称必须全局唯一。 expvar.Publish 遇到已经注册的同名变量会触发 panic。把指标注册集中在包初始化阶段，并给名称加清晰前缀。
3. 返回值必须是合法 JSON。 自定义 Var.String 或 Func 不能返回任意文本；结构体、数字、布尔值和字符串更容易保持合法编码。

最后可以用这张表快速选择：

相关问题

expvar 能不能让客户端修改指标？ 默认的 /debug/vars 是读取接口；客户端不能靠 GET 请求修改值，应用内部仍可用指标类型提供的方法更新。

为什么不直接返回 JSON 字符串？ expvar.Func 返回 Go 值后由标准库编码，通常比手写转义更不容易产生非法 JSON。

为什么要单独使用 Handler？ 当指标端口、业务端口或鉴权策略不同，用 Handler() 挂入独立路由更容易控制暴露范围。