怎样把 flight recorder 快照写入故障诊断端点

把 runtime/trace.FlightRecorder 接到 HTTP 故障诊断端点时，稳妥做法不是直接把 WriteTo 对着 http.ResponseWriter 写。更容易维护的实现是：端点只接受经过管理员鉴权的 POST，用单槽闸门拒绝并发导出，先把快照写入临时 trace 文件；成功后再设置下载响应头并复制给客户端，请求结束立即删除临时文件。这样快照阶段失败时仍能返回清晰的 HTTP 状态，也不会把半截文件伪装成成功下载。

官方参考：https://pkg.go.dev/runtime/trace、https://go.dev/blog/flight-recorder、https://pkg.go.dev/net/http、https://pkg.go.dev/net/http/httptest。

先把故障诊断端点的契约定清楚

这个端点导出的执行轨迹可能包含函数、资源使用和运行时事件等诊断信息，不应暴露在普通业务路由上。最少要确定五条契约：只允许 POST；必须通过现有管理员鉴权；记录器未启用时返回 503；已有导出时返回 409；成功响应使用附件下载并禁止缓存。反向代理和服务自身还要给大文件下载留出合理写超时，但不建议为了一个诊断端点关闭整个服务器的超时保护。

用可测试接口包住 FlightRecorder

*trace.FlightRecorder 已经提供 Enabled 和 WriteTo，因此可以用一个很小的接口承接它。接口不是为了重复封装标准库，而是让 Handler 测试不必真的启动运行时追踪。单槽 channel 同时充当非阻塞锁：拿不到槽位就立即返回 409，避免两个下载请求互相等待。

package diagnostics

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"strconv"
	"time"
)

type Snapshotter interface {
	Enabled() bool
	WriteTo(io.Writer) (int64, error)
}

type SnapshotHandler struct {
	Recorder  Snapshotter
	Authorize func(*http.Request) bool
	Gate      chan struct{}
	Logger    *log.Logger
}

func NewSnapshotHandler(recorder Snapshotter, authorize func(*http.Request) bool, logger *log.Logger) *SnapshotHandler {
	// 单槽 channel 只允许一个请求进入快照阶段。
	return &SnapshotHandler{
		Recorder: recorder, Authorize: authorize,
		Gate: make(chan struct{}, 1), Logger: logger,
	}
}

func (h *SnapshotHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	// 导出会产生文件，只允许显式 POST 触发。
	if r.Method != http.MethodPost {
		w.Header().Set("Allow", http.MethodPost)
		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
		return
	}
	// 未配置鉴权函数时默认拒绝，避免误挂到公开路由。
	if h.Authorize == nil || !h.Authorize(r) {
		http.Error(w, "forbidden", http.StatusForbidden)
		return
	}
	// 未启动的记录器无法提供有效快照。
	if h.Recorder == nil || !h.Recorder.Enabled() {
		http.Error(w, "flight recorder unavailable", http.StatusServiceUnavailable)
		return
	}

	select {
	case h.Gate 

这里没有调用 Stop。Flight recorder 是服务级组件，导出一次快照后仍应继续记录新的运行时事件。只有服务关闭或明确结束记录时才停止它。标准库还规定，同一记录器一次只能有一个 goroutine 执行 WriteTo；Handler 自己控制并发，比把标准库错误直接暴露给客户端更容易观察和告警。

在服务启动时创建记录器，在私有路由中注册

记录窗口和最大字节数属于容量策略，应在启动阶段确定。MinAge 表示希望尽量保留的最近时长，MaxBytes 控制记录器最多占用的字节数；实际窗口仍受事件量和内部追踪约束。下面只展示注册关系，adminPolicy 应接入项目已有的 mTLS、网关身份或管理员会话，不要在示例代码里硬编码 token。

recorder := trace.NewFlightRecorder(trace.FlightRecorderConfig{
	// 尽量保留最近 30 秒，同时限制记录器的内存规模。
	MinAge:   30 * time.Second,
	MaxBytes: 64 

如果服务有独立管理监听器，把 adminMux 只绑定到回环地址、运维网或受控 sidecar；若必须经过统一网关，还应限制请求频率并记录操作者身份。不要把令牌、Cookie 或完整请求头写入日志，审计只需要身份标识、触发时间、导出字节数、耗时和错误类别。

用 httptest 覆盖交互边界

测试重点不是追踪文件内部格式，而是端点行为：方法不符、鉴权失败、记录器不可用、忙碌和成功下载。下面的假实现让测试稳定地产出字节，不依赖运行时事件量。

type fakeSnapshotter struct {
	enabled bool
	data    []byte
}

func (f fakeSnapshotter) Enabled() bool { return f.enabled }

func (f fakeSnapshotter) WriteTo(w io.Writer) (int64, error) {
	// 测试只验证传输契约，不伪造真实 trace 格式。
	n, err := w.Write(f.data)
	return int64(n), err
}

func TestSnapshotDownload(t *testing.T) {
	recorder := fakeSnapshotter{enabled: true, data: []byte("trace-bytes")}
	// 测试鉴权固定放行，生产环境应注入真实管理员策略。
	h := NewSnapshotHandler(recorder, func(*http.Request) bool { return true }, log.Default())

	req := httptest.NewRequest(http.MethodPost, "/debug/flight-recorder", nil)
	res := httptest.NewRecorder()
	h.ServeHTTP(res, req)

	// 成功响应必须同时具备状态、缓存策略和完整字节。
	if res.Code != http.StatusOK {
		t.Fatalf("status = %d", res.Code)
	}
	if got := res.Header().Get("Cache-Control"); got != "no-store" {
		t.Fatalf("cache-control = %q", got)
	}
	if got := res.Body.String(); got != "trace-bytes" {
		t.Fatalf("body = %q", got)
	}
}

还可以在测试里预先向 h.Gate 写入一个值，再发请求并断言得到 409；把 enabled 设为 false，可验证 503。方法检查应断言 405 和 Allow: POST，鉴权失败应断言 403。这样修改 Handler 时，最重要的用户反馈不会悄悄变化。

运行时边界要和代码一起上线

还要区分快照失败和下载失败：前者发生在响应头发送前，可以返回 500；后者往往发生在客户端断开或网络超时之后，此时 HTTP 状态已经不可逆，只能记录日志和指标。若下载经常被截断，应优先检查反向代理缓冲、服务器 WriteTimeout、临时目录空间和客户端超时，而不是重复调用 WriteTo。

常见问题

为什么不直接把 WriteTo 的目标设成 ResponseWriter？

直接写最省代码，但一旦中途失败，响应可能已经是 200 且包含半截 trace。临时文件方案多一次磁盘读取，却能在开始下载前确认快照完整，也避免把整个文件放进内存，适合运维诊断端点。

导出完成后要不要 Stop 再 Start？

不需要。WriteTo 是对当前移动窗口的快照，完成后记录器可以继续工作。频繁停止会破坏连续诊断窗口，也会增加生命周期竞态。

为什么忙碌时返回 409，而不是让请求排队？

诊断请求通常由人工或自动化临时触发，排队会让旧请求占用磁盘和连接，还可能在操作者不知情时连续生成多份大文件。409 能明确告诉调用方已有快照进行中，由调用方决定稍后重试。