Go http.Transport.RegisterProtocol 怎样接入自定义协议请求

http.Transport.RegisterProtocol 适合“同一个 http.Client 还要识别一个自定义 URL scheme”的场景。它不是重新造一套 Client，而是在 Transport 的协议路由旁挂接一个 RoundTripper：匹配到指定 scheme 时交给你的实现；实现返回 http.ErrSkipAltProtocol 时，再让 Transport 按默认路径处理这次请求。

官方地址：https://pkg.go.dev/net/http@go1.27.3#Transport.RegisterProtocol

我在设计这类适配时最容易踩的坑，是把“协议已经注册”误解成“Cookie、重定向、认证和响应体语义都自动具备”。真正需要做的只是把协议边界放在 Transport 层，再明确 RoundTripper 对响应和回退的责任。

为什么 RegisterProtocol 不是另一套 Client

普通的 http.Client 负责较高层的请求体验，例如 Cookie 和重定向；http.Transport 是更底层的 RoundTripper 实现，负责把请求交给具体传输路径。RegisterProtocol 的作用是给 Transport 增加一个 scheme 到 RoundTripper 的映射。

因此，方案选择可以先这样分：

用 RoundTripper 接住一个自定义 scheme

注册时要同时准备 scheme 和 RoundTripper。下面的实现只返回一个内存响应，用来展示接口边界；它不是文件协议、FTP 或网络代理的完整实现，也没有声称执行过。

package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

// noteRoundTripper 只演示自定义 scheme 如何被路由到 RoundTrip。
type noteRoundTripper struct{}

func (noteRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
    // 先限制协议边界，避免把普通 HTTP 请求误当成 notes 请求。
    if req.URL.Scheme != "notes" {
        return nil, http.ErrSkipAltProtocol
    }

    // 自定义实现必须构造可消费的响应体，并交代状态与请求引用。
    body := io.NopCloser(strings.NewReader("notes scheme response"))
    return &http.Response{
        StatusCode: http.StatusOK,
        Status:     "200 OK",
        Header:     make(http.Header),
        Body:       body,
        Request:    req,
    }, nil
}

func main() {
    // Transport 负责 scheme 路由；Client 仍是调用方看到的入口。
    transport := &http.Transport{}
    transport.RegisterProtocol("notes", noteRoundTripper{})
    client := &http.Client{Transport: transport}

    // 该 URL 只用于说明路由选择，正式业务还应补上自己的协议语义。
    req, err := http.NewRequest(http.MethodGet, "notes://local/today", nil)
    if err != nil {
        fmt.Println("创建请求失败:", err)
        return
    }
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("发送请求失败:", err)
        return
    }
    defer resp.Body.Close() // 读取完成后关闭响应体，避免资源悬挂。

    data, err := io.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("读取响应失败:", err)
        return
    }
    fmt.Println(resp.Status, string(data))
}

这里最关键的不是字符串内容，而是三层边界：RegisterProtocol("notes", ...) 注册 scheme，RoundTrip 负责生成符合约定的响应，Client.Do 继续作为调用入口。真实适配器要根据自己的协议填充状态码、Header、Body 和错误语义，并确保 Body 能被调用方关闭。

ErrSkipAltProtocol 代表什么

ErrSkipAltProtocol 不是“请求失败”的业务错误。根据官方文档，如果已注册的 RoundTripper 返回它，Transport 会把这一次请求当作没有注册该协议一样，继续走 Transport 自己的处理逻辑。这个回退只表达“当前适配器不接管”，不替你生成响应，也不保证任意 scheme 都能被默认 Transport 处理。

type selectiveRoundTripper struct {
    fallback http.RoundTripper
}

func (s selectiveRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
    // 只接管满足业务条件的 notes 请求，其余请求交回默认路径。
    if req.URL.Scheme != "notes" || req.URL.Host != "local" {
        return nil, http.ErrSkipAltProtocol
    }
    if s.fallback == nil {
        return nil, fmt.Errorf("缺少自定义协议实现")
    }
    // 这里的 fallback 只是示例依赖，真实实现应返回完整 HTTP 响应。
    return s.fallback.RoundTrip(req)
}

这个示例的判断顺序也体现了一个取舍：scheme 相同不等于所有请求都由同一个适配器处理。可以继续检查 Host、路径或业务允许的资源范围；但如果请求不属于自定义协议的责任范围，应明确返回 ErrSkipAltProtocol，不要吞掉请求，也不要伪造一个成功响应。

高层语义要不要自己补

如果只是给内部资源提供一个可测试的 scheme，轻量 RoundTripper 往往够用；如果要模拟完整 HTTP 语义，就要把责任拆清。Transport 文档把自定义 RoundTripper 的责任描述为模拟 HTTP 请求语义，而 Client 的 Cookie、重定向等能力仍属于更高层。

我通常按下面的条件做决定：

几个容易混淆的问题

RegisterProtocol 会改写 http 和 https 吗？

它注册的是指定 scheme 的处理器。只为 notes 注册适配器，并不等于替换所有 HTTP 请求；普通 HTTP/HTTPS 仍取决于 Transport 自身的处理配置。

RoundTripper 返回响应后还需要关闭 Body 吗？

需要。适配器要返回调用方能够读取和关闭的 Body；调用方拿到响应后仍应按通常的 Client 使用方式处理关闭和读取错误。

ErrSkipAltProtocol 能让任意自定义 scheme 自动工作吗？

不能。它只是回退信号。默认 Transport 是否能处理该 scheme 仍是另一件事；如果没有可用的默认路径，最终仍应返回明确错误。

总结一下：先确认需求是不是“为指定 scheme 选择另一套 RoundTripper”，再用 RegisterProtocol 注册；自定义实现要对响应语义负责；不接管时用 ErrSkipAltProtocol 交回 Transport；Cookie、重定向和资源关闭则按 Client 与调用方各自的责任处理。