当前位置：首页 > 文章列表 > Golang > Go教程 > Go expvar.Func 怎么发布只读的动态指标

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

来源：17golang原创 2026-11-05 07:02:15 0浏览收藏

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

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

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

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

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

需求	更合适的类型	原因
请求完成时累加一次	`expvar.Int`	写入路径明确，读取成本低
查看时读取当前状态	`expvar.Func`	不需要额外同步一份快照
按键维护多组计数	`expvar.Map`	每个键可以独立更新

expvar Func 将只读回调连接到动态指标对象和 JSON 输出的结构说明图 — 图1：结构说明图，展示读时回调、expvar 变量与 JSON 输出之间的静态关系。

回调只返回 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 只负责变量格式化，不负责访问控制。