登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  Golang >  Go教程

Go httptrace.WroteRequest 怎样记录请求写出结果

来源:17golang原创

时间:2026-11-17 05:52:42 376浏览 收藏

如果你在排查 Go HTTP 客户端请求失败,最容易混淆的是“请求有没有写出去”和“服务端最终返回了什么”。httptrace.ClientTrace.WroteRequest专门观察前一个阶段:Transport 写完请求及请求体后回调,并通过 WroteRequestInfo.Err 告诉你写出阶段是否遇到错误。

官方地址:https://pkg.go.dev/net/http/httptrace#ClientTrace.WroteRequest

它不是成功响应通知。写出成功后,服务端仍可能返回 4xx/5xx;请求也可能在写出之前就因为连接、DNS 或上下文取消失败。实战中应把 WroteRequest、http.Client.Do 的错误和 HTTP 状态码分别记录。

Go httptrace 请求阶段与 WroteRequest 回调边界说明图
图1:结构图展示 Go HTTP 请求从连接到写出、收到响应的阶段关系,并标出 WroteRequest 的观察边界;这不是运行截图。

先区分写出阶段和响应阶段

可以把一次 HTTP round trip 拆成三类信号:

信号回答的问题不能推出的结论
WroteRequest本次请求及请求体写出时是否出错不能推出服务端处理成功
Do 返回的 errorTransport 是否完成了可交付给调用方的响应没有 error 不代表状态码是 2xx
resp.StatusCode服务端返回的 HTTP 结果不能单独说明请求是否完整写出

例如,服务端返回 500 时,通常可以同时看到 WroteRequestInfo.Err == nil、Do 没有错误、StatusCode == 500。这表示请求成功写出,但业务处理失败。反过来,写出阶段出错时,调用方通常会从 Do 得到一个传输错误,是否拥有完整响应则要以 Do 的返回值为准。

把 ClientTrace 挂到请求上下文

httptrace不是给 http.Client 设置全局回调,而是把 ClientTrace 放入本次请求的 context。下面的最小结构把每次写出事件保存下来,再单独处理最终的响应。

package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptrace"
	"sync"
	"time"
)

type writeEvent struct {
	At      time.Time
	ErrText string
}

func doRequest(ctx context.Context, url string) ([]writeEvent, int, error) {
	// 用互斥锁保存回调数据,因为 trace 回调可能在不同 goroutine 中执行。
	var mu sync.Mutex
	events := make([]writeEvent, 0, 2)

	trace := &httptrace.ClientTrace{
		WroteRequest: func(info httptrace.WroteRequestInfo) {
			event := writeEvent{At: time.Now()}
			if info.Err != nil {
				// 只把本次写出错误放进事件,最终 Do 错误另行记录。
				event.ErrText = info.Err.Error()
			}
			mu.Lock()
			events = append(events, event)
			mu.Unlock()
		},
	}

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return events, 0, fmt.Errorf("创建请求失败: %w", err)
	}
	// WithClientTrace 只影响挂载到这个 context 的 HTTP 请求。
	req = req.WithContext(httptrace.WithClientTrace(req.Context(), trace))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return events, 0, fmt.Errorf("请求未得到完整响应: %w", err)
	}
	defer resp.Body.Close() // 读取或记录响应后必须释放连接资源。
	return events, resp.StatusCode, nil
}

这里有三个细节值得保留:

  1. 回调只负责采集轻量数据,不在其中做阻塞 I/O 或复杂业务。
  2. WroteRequestInfo.Err 为空表示本次写出没有报告错误,不等同于 HTTP 成功。
  3. Do 成功返回 Response 后仍要关闭 Body,否则连接复用会受到影响。

用稳定的记录结构保存结果

只记录一个布尔值很快就会丢失上下文。建议至少保存写出事件时间、写出错误、Transport 最终错误和状态码:

type requestResult struct {
	WroteCount  int
	WroteErrors []string
	DoError     string
	StatusCode  int
}

func summarize(events []writeEvent, statusCode int, doErr error) requestResult {
	result := requestResult{WroteCount: len(events), StatusCode: statusCode}
	for _, event := range events {
		if event.ErrText != "" {
			// 保留每一次写出错误,便于识别重试或连接切换。
			result.WroteErrors = append(result.WroteErrors, event.ErrText)
		}
	}
	if doErr != nil {
		// Do 错误描述最终交付给调用方的传输结果。
		result.DoError = doErr.Error()
	}
	return result
}

推荐用“事件 + 最终结果”的两层结构,而不是在回调里直接把某个共享字段改成 success。这样即使同一次逻辑请求出现多次写出,也能看到每次尝试的顺序和错误。

处理重试与并发回调

官方文档明确说明,WroteRequest 在请求被重试时可能调用多次;ClientTrace 的回调也可能并发执行,甚至在请求已经完成或失败后才被调用。因此不能假设“一次 Do 对应一次 WroteRequest”。

Go httptrace WroteRequest 多次回调与最终结果决策说明图
图2:说明图对比首次写出、重试写出和最终响应三个状态,强调多次回调不能直接覆盖成单一结论;这不是运行截图。

记录时可以按以下规则处理:

  • 每次回调追加一条事件,不覆盖前一条。
  • 需要计数时使用互斥锁或原子变量;需要保存错误文本时使用受保护的切片。
  • 把回调采集和日志输出解耦,避免日志系统变慢后反过来影响请求路径。
  • 如果请求经过重定向,要把每个 round trip 当成独立观测范围;ClientTrace 本身没有跨整组重定向的统一 hook。

用决策表判断最终结论

WroteRequestDo errorResponse建议结论
无事件有无可能在连接或请求写出前失败,优先看 Transport 错误
有事件且 Err 为空无4xx/5xx请求写出成功,服务端或业务层返回失败状态
有事件且 Err 非空有无写出阶段异常,结合错误链判断是否发生重试
多条事件无或有有或无不要只看最后一条,按 attempt 和时间线还原过程

最实用的日志字段可以是:request_id、attempt、wrote_error、do_error、status_code 和耗时。这样排查“服务端没收到”“请求写到一半断开”“服务端收到但返回 500”时,证据会落在不同字段里。

常见问题

WroteRequest 没触发,是不是 httptrace 失效了?

不一定。请求可能在建立连接、解析地址或真正写请求前就失败,也可能没有使用带 trace 的那个 context。先确认 req = req.WithContext(...) 在调用 Do 之前执行,再看 Do 返回的错误。

WroteRequest Err 为空,就能认为接口调用成功吗?

不能。它只说明写出阶段没有报告错误,必须继续检查 Do 是否返回响应以及响应状态码。

为什么同一次请求出现多条 WroteRequest?

重试、连接切换或 Transport 的请求尝试都可能让回调多次触发。把每次回调作为事件保存,并在记录中增加 attempt 或时间戳,不要简单覆盖。

回调里可以直接写数据库吗?

不建议。回调位于请求链路中,而且可能并发调用。更稳妥的做法是写入有界 channel 或轻量内存事件,再由独立协程批量落盘。

总结

httptrace.WroteRequest 解决的是“请求写出阶段发生了什么”,核心字段是 WroteRequestInfo.Err。把它和 Do 错误、HTTP 状态码分层记录,再考虑多次回调与并发,才能把 Go HTTP 客户端的失败定位从一个模糊的 error 变成可复盘的时间线。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>