Go expvar 暴露运行时指标的接口设计

Go 服务可以用 expvar 把计数器和运行时变量以 JSON 暴露给读取方。接口设计时，要先确定指标的含义、注册位置和访问范围，再显式把 expvar.Handler() 挂到所用的路由器上。本文用一个仅监听本机的小服务，完整串起这些决定。

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

先约定业务计数和读取入口

设定一个原创示例：POST /work 表示接受一次业务请求，GET /debug/vars 用于读取指标。业务字段命名为 jobs_accepted_total，单位是请求数；它既不是成功完成量，也不是当前排队长度。先把这一句约定写清楚，接入图表时才不会误解数据。

expvar 默认注册的 cmdline 和 memstats 也会出现在指标集合中。读取接口提供的是进程变量集合，业务计数只是其中一项。不要把该接口当作只返回本文一个字段的固定响应。

本项目只需安装Go工具链，保存一个 main.go，不依赖第三方模块。下面代码按标准库公开接口编写，运行命令和结果判断供读者复现，不是已经执行的测试记录。

用显式路由组装一个最小服务

将指标注册放在包级初始化位置，处理器里只更新值。注册表中的名称必须唯一，重复注册会触发panic，因此不能在每次请求或反复执行的构造函数中重新调用 NewInt。示例使用 NewServeMux 并显式设置 Server.Handler，让实际服务的路由一目了然。

package main

import (
    "context"
    "errors"
    "expvar"
    "fmt"
    "log"
    "net/http"
    "os"
    "os/signal"
    "time"
)

// 只在进程初始化时注册一次；单位是被接受的业务请求数。
var jobsAccepted = expvar.NewInt("jobs_accepted_total")

func run() error {
    mux := http.NewServeMux()
    mux.HandleFunc("/work", func(w http.ResponseWriter, r *http.Request) {
        // 示例只接收POST，不把无效方法计入业务请求。
        if r.Method != http.MethodPost {
            w.Header().Set("Allow", http.MethodPost)
            http.Error(w, "请使用POST", http.StatusMethodNotAllowed)
            return
        }
        // 此处表示接受请求，不表示后台任务已经完成。
        jobsAccepted.Add(1)
        w.WriteHeader(http.StatusAccepted)
    })
    mux.HandleFunc("/debug/vars", func(w http.ResponseWriter, r *http.Request) {
        // 显式限制GET，使自定义挂载点也遵守读取约定。
        if r.Method != http.MethodGet {
            w.Header().Set("Allow", http.MethodGet)
            http.Error(w, "请使用GET", http.StatusMethodNotAllowed)
            return
        }
        expvar.Handler().ServeHTTP(w, r)
    })

    srv := &http.Server{
        Addr: "127.0.0.1:9090",
        Handler: mux,
        ReadHeaderTimeout: 5 * time.Second,
    }
    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
    defer stop()
    done := make(chan error, 1)
    go func() {
        // Serve返回错误必须交给主流程处理。
        done 

expvar 的内置变量更新操作具备原子性，所以本例用 Add(1) 更新计数，不另外维护一个共享普通整数。原子更新不意味着所有指标的一次读取都是跨字段事务快照。若未来同时记录接受量与完成量，采集端要允许读取时出现短暂的时间差。

本例把调试处理器显式挂到自己的mux。expvar导入时的默认路由注册，不会自动把路由复制进每个新建的mux；使用自定义mux却忘记挂载，是排查404时应先看的位置。

启动服务并观察计数变化

在空目录保存代码后执行下面命令。服务在前台持续运行，后面的curl在另一个命令会话执行；复现结束在服务会话按Ctrl+C触发关闭。

# 在包含main.go的空目录中初始化，再前台运行服务。
go mod init example.com/expvar-demo
go run .

# 在另一个命令会话中读取初始指标。
curl --fail http://127.0.0.1:9090/debug/vars

# 发送两次业务请求，然后再次读取指标。
curl --fail -X POST http://127.0.0.1:9090/work
curl --fail -X POST http://127.0.0.1:9090/work
curl --fail http://127.0.0.1:9090/debug/vars

新进程的业务计数应从零开始；在没有其他调用的前提下，两次POST之后应为2。这里给出的是示例语义推导，不提供伪造的终端日志。重点查看字段是否存在、计数是否随业务请求增加，以及GET读取本身是否没有增加业务计数。

示例将POST定义为接受动作，返回202且没有响应正文，因此curl不显示业务文本属于预期。端口被占用时，监听错误会返回主流程并以非零状态结束；先处理端口冲突再运行。

接入部署环境时划分访问范围

地址 127.0.0.1:9090 限定本机监听；同机进程仍可能访问它，这不是身份认证。示例没有把调试接口公开给外部调用方。实际部署可将业务和管理接口放到不同监听器，并通过内部采集网络或受控代理连接管理接口。

管理接口的访问策略应作用于整个指标集合。尤其需要注意默认字段包含启动参数与运行时信息；不要在启动参数中放置敏感值，也不要认为更换URL路径就提供了鉴权。容器内的回环地址属于容器自身，宿主机采集端不一定能按示例地址访问，应结合所用网络模式安排采集位置。

用指标含义判断结果是否符合预期

字段名和单位应保持稳定，后续增加指标时另写语义约定。不要把用户ID或任意请求参数用作无限增长的Map键；如果需要按结果分类，先定义有限的类别，再安排采集端如何解释这些类别。

为什么导入expvar后自定义路由仍然404？

确认实际Server使用哪个Handler，以及对应mux是否挂载了 expvar.Handler()。默认路由和新建的mux是不同对象，不能只看导入语句。

能否用计数器直接显示每秒请求量？

本例提供进程累计值。每秒请求量需要采集端按时间差计算，并处理重启产生的计数重置；不要直接把累计数当成速率。

自定义expvar.Func能不能查询数据库？

Func在读取时调用所提供的函数。本文建议只返回低成本的内存状态；如果把昂贵查询塞进去，每次采集都可能给服务增加额外工作。需要外部数据时，可由独立任务更新缓存状态，再让指标读取缓存。

相关接口：expvar变量、注册与Handler，http.Server及关闭方法。路由划分、指标命名与服务代码为本文原创示例。