Go expvar.Func 怎么发布只读的动态指标

如果指标不是“写入时累加”，而是希望每次查看时根据当前状态重新计算，expvar.Func 很合适。它的类型就是 func() any：调用方读取指标时执行回调，再把返回值按 JSON 形式输出。这样可以发布队列长度、当前缓存项数、配置快照等只读动态值，而不用额外维护一份同步变量。

官方资料：https://pkg.go.dev/expvar#Func

最小做法是让回调只做一次快速、并发安全的读取，再用 expvar.Publish("名称", expvar.Func(回调)) 注册。它适合“读时计算”，不适合把慢查询、网络请求或带副作用的任务塞进指标端点。

先判断：这个值是不是应该在读取时计算

expvar.Int、expvar.Float 和 expvar.Map 适合业务代码主动更新的累计量，例如请求总数。expvar.Func 则不保存一个可写的当前值，它每次被读取都会调用函数。两者的接口决策可以这样记：

回调只返回 JSON 能表达的当前状态

官方定义中，Func 通过调用函数并使用 JSON 格式化返回值来实现 Var。因此回调最好返回数字、字符串、布尔值或由这些值组成的结构体/映射，并把共享数据的读取动作控制在一个很小的范围内。

package main

import (
    "expvar"
    "net/http"
    "sync/atomic"
)

var inFlight atomic.Int64

func main() {
    // 回调在读取指标时执行，不在这里缓存一个固定结果。
    expvar.Publish("in_flight_requests", expvar.Func(func() any {
        // atomic.Load 保证并发读取不会产生数据竞争。
        return inFlight.Load()
    }))

    // 使用标准库的调试端点输出所有已注册变量。
    http.ListenAndServe(":8080", nil)
}

如果需要返回多个字段，可以让回调返回一个结构体。字段名会成为 JSON 键，但不要把内部对象、指针或未受控的字符串直接暴露到调试端点；指标接口同样需要遵守最小暴露原则。

type queueSnapshot struct {
    Depth int64  `json:"depth"`
    State string `json:"state"`
}

var queueDepth atomic.Int64

func currentQueue() any {
    // 同一时刻读取相关字段，避免返回带有明显矛盾的快照。
    depth := queueDepth.Load()
    state := "ready"
    if depth > 1000 {
        state = "backlog"
    }
    return queueSnapshot{Depth: depth, State: state}
}

注册方式决定指标出现在哪里

注册后，默认的 expvar 包会把变量提供给 /debug/vars。新式 net/http 路由可以直接挂载包返回的 Handler；如果应用已经有自己的 mux，也可以把它安装到指定路径。

func registerMetrics() {
    // 名称必须在全局 expvar 表中唯一，重复注册会触发 panic。
    expvar.Publish("queue_snapshot", expvar.Func(currentQueue))
}

func main() {
    registerMetrics()

    mux := http.NewServeMux()
    // 将 expvar 的 JSON Handler 放到自定义调试路径。
    mux.Handle("GET /internal/vars", expvar.Handler())
    http.ListenAndServe(":8080", mux)
}

如果只使用标准默认 mux，可以直接导入 expvar 并使用默认的 /debug/vars。无论哪种方式，调试端点都应放在受控网络或鉴权边界之后；expvar.Func 只负责变量格式化，不负责访问控制。

并发与性能边界要提前写进回调

每次读取都会执行回调，所以回调里不应做数据库全表扫描、远程请求、磁盘遍历或修改业务状态。调试端点被监控系统频繁抓取时，这些操作会把“查看指标”变成新的负载来源。

共享状态需要使用原子类型、互斥锁或不可变快照。若一次读取需要组合多个字段，可以在业务侧定期构造一份快照，回调只返回这份快照；不要在回调里临时拼接一个需要长时间持锁的对象。回调没有错误返回值，复杂采集失败时应提前把失败状态编码为可读字段，而不是把网络错误处理逻辑塞进 Func。

• 回调保持无副作用：只读、快速、可重复调用。
• 返回值保持 JSON 友好，避免不可编码的函数、通道或循环引用。
• 指标名全局唯一，注册动作集中管理，避免初始化顺序难以排查。
• 把端点放在内部网络或认证后的 mux 下，不能把 expvar 当作权限控制。

常见问题

expvar.Func 会自动缓存上一次结果吗？

不会。它的语义是读取时调用函数，因此回调必须能承受读取频率；需要缓存时应由业务侧明确维护快照。

为什么不用 expvar.Int 保存这个值？

如果值来自业务事件的累加，Int 更直接；如果值是读取瞬间的派生状态，Func 可以避免重复维护一个可能过期的副本。

expvar.Func 能替代 Prometheus 指标吗？

本文只讨论标准库 expvar 的 JSON 暴露方式。是否采用 Prometheus 等独立指标系统，要根据采集协议、标签维度、聚合和告警需求另行决策。