Go http.Request.WriteProxy 生成代理请求的格式与写入方法

需要把 Go 请求交给一个 HTTP 代理时，关键不是把目标地址拼接到字符串里，而是使用 http.Request.WriteProxy。它会按代理期望的 absolute-form 写出请求行，例如把 /v1/items?page=2 写成带有 scheme 和 host 的完整 URI，同时补上 Host 头。普通 Request.Write 则更接近直连服务器使用的 origin-form。

先分清 Write 和 WriteProxy 的请求格式

HTTP/1.1 直连服务器时，请求行通常是 GET /v1/items?page=2 HTTP/1.1，这叫 origin-form。代理需要先判断目标主机，因此请求行要保留完整目标，例如 GET http://api.internal:8080/v1/items?page=2 HTTP/1.1，这就是 absolute-form。

WriteProxy 只解决“把内存中的 Request 写成代理看到的字节格式”。它不是 Transport.Proxy 的替代品，也不会自动拨号、连接代理或添加代理认证。把这几个职责拆开，调试时才能知道问题是在请求序列化、代理连接还是上游响应。

用完整 URL 创建代理格式请求

目标地址要包含 scheme 和 host。下面的示例只演示序列化，不会真的访问代理；bytes.Buffer 接收生成的 HTTP/1.x 文本，便于把它交给后续连接层或测试夹具。

package main

import (
    "bytes"
    "fmt"
    "net/http"
)

func main() {
    // URL 保存代理请求行需要的 scheme、host、path 和 query。
    req, err := http.NewRequest(http.MethodGet, "http://api.internal:8080/v1/items?page=2", nil)
    if err != nil {
        // URL 解析失败时不要继续写出半成品请求。
        panic(err)
    }
    req.Header.Set("User-Agent", "proxy-lab/1.0")
    // Host 为空时，WriteProxy 会回退到 req.URL.Host；这里显式设置便于演示边界。
    req.Host = "api.internal:8080"

    var wire bytes.Buffer
    if err := req.WriteProxy(&wire); err != nil {
        // 写入目标可能是网络连接或文件，必须处理底层 writer 的错误。
        panic(err)
    }
    fmt.Print(wire.String())
}

按这个请求的字段，核心请求行应包含 GET http://api.internal:8080/v1/items?page=2 HTTP/1.1，并出现 Host: api.internal:8080。这是根据 Request 字段序列化出的格式说明，不应把它误写成真实抓包结果。

Host 与 URL 的边界要单独检查

代理请求里最容易混淆的是“请求行目标”和“Host 头”。URL 提供绝对 URI 所需的 scheme 与 host；Request.Host 如果非空，则用于 Host 头，否则回退到 URL.Host。因此，修改 req.Host 不等于修改了代理要访问的 URL。

写入失败与接入代理链路的处理方案

如果目标 writer 是连接、文件或带限流的包装器，WriteProxy 的返回错误就是这一层的失败信号。不要只检查 buffer 是否有内容，因为部分写入后仍可能返回错误。生产代码通常按“构造 Request → 校验 URL → 写入代理连接 → 处理代理响应”的顺序组织，但实际连接复用、TLS CONNECT 和认证交给对应的 Transport 或代理客户端。

如果目标是通过 http.Client 发请求，优先配置 Transport.Proxy，让标准库管理连接与请求生命周期；只有在实现自定义代理协议、记录原始线格式或编写协议测试时，才直接使用 WriteProxy。这样既能保留绝对 URI，又不会重复实现连接池和响应读取。

常见问题

WriteProxy 会自动连接代理吗？

不会。它只向给定的 io.Writer 写 HTTP/1.x 请求格式，连接、认证和响应读取需要其他组件完成。

为什么请求行要包含完整 URL？

HTTP 代理需要从请求行识别目标 scheme 和 host，absolute-form 正是为这个转发场景准备的格式。

Request.Host 为空时会怎样？

Host 头会使用 URL.Host。但如果 URL 本身没有有效 host，构造出的代理请求就无法表达明确目标，应在写入前处理错误或拒绝该请求。

Write 和 WriteProxy 能互相替代吗？

不能。直连服务器通常使用路径形式，代理转发需要绝对 URI；应按接收方选择对应方法。

把 WriteProxy 当成“代理请求的序列化边界”就不容易误用：URL 决定目标，Host 决定 Host 头，writer 决定字节去向，而代理连接和认证由后续传输层负责。