Go HTTP/3 怎样选择 quic-go 适配层

Go 项目接入 HTTP/3 时，最稳妥的选择是先使用 quic-go 已经封装好的 http3.Transport 或 http3.Server。只有需要自定义 UDP 绑定、让客户端和服务端共享一个 socket，或在同一条 QUIC 连接上做 ALPN 多协议分流时，才把 quic.Transport 放进适配层。这样既能保留 http.Client 的调用方式，也不会过早接管连接生命周期。

官方地址：https://quic-go.net/

Go HTTP/3 的默认入口应该怎样分层

HTTP/3 运行在 QUIC 之上，而 QUIC 使用 UDP。quic-go 的 http3 包已经把 HTTP 请求语义接到 QUIC 连接上：客户端侧的 Transport 实现 http.RoundTripper，服务端侧的 Server 接受 HTTP Handler。因此选型可以先看调用面，而不是先看底层连接。

普通 HTTP/3 客户端直接使用 http3.Transport

如果目标只是让一个 Go 客户端访问 HTTP/3 服务，不需要自己绑定本地 UDP 端口，也不需要拿到 QUIC 连接，那么把 http3.Transport 作为 http.Client.Transport 就够了。Close 应在进程退出或客户端不再使用时调用，避免连接池和 QUIC 资源长期留存。

package main

import (
    "context"
    "crypto/tls"
    "fmt"
    "net/http"
    "time"

    "github.com/quic-go/quic-go/http3"
)

func fetch(ctx context.Context, url string) error {
    tr := &http3.Transport{
        TLSClientConfig: &tls.Config{
            MinVersion: tls.VersionTLS13, // HTTP/3 使用 TLS 1.3 握手
        },
    }
    defer tr.Close() // 释放连接池中的 QUIC 连接

    client := &http.Client{Transport: tr}
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return err
    }
    resp, err := client.Do(req)
    if err != nil {
        return err // 网络失败、握手失败都从这里返回
    }
    defer resp.Body.Close() // 读取响应后关闭响应体
    fmt.Println(resp.Status)
    return nil
}

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel() // 请求超时后取消本次生命周期
    _ = fetch(ctx, "https://example.com/")
}

这条路径的关键是“兼容 HTTP 客户端接口”，而不是把所有 QUIC 参数都暴露出来。证书信任、请求超时和响应体关闭仍由应用负责；是否走 HTTP/3 则由目标端点、网络路径和部署策略决定。

需要共享 UDP 或自定义连接时再接入 quic.Transport

当应用已经拥有一个 quic.Transport，或者需要固定本地 UDP socket 时，才通过 http3.Transport.Dial 把拨号动作接回自己的传输层。这里的 Dial 不是另一个 HTTP 客户端，而是“谁创建 QUIC 连接”的控制点。

tr := &quic.Transport{}
h3tr := &http3.Transport{
    TLSClientConfig: &tls.Config{},
    Dial: func(ctx context.Context, addr string, tlsCfg *tls.Config, quicCfg *quic.Config) (quic.EarlyConnection, error) {
        udpAddr, err := net.ResolveUDPAddr("udp", addr)
        if err != nil {
            return nil, err // 地址解析失败时不创建连接
        }
        return tr.DialEarly(ctx, udpAddr, tlsCfg, quicCfg) // 复用自定义 QUIC 传输
    },
}
defer h3tr.Close() // 先停止 HTTP/3 连接池
defer tr.Close()   // 再释放底层 UDP/QUIC 资源

如果同一个 UDP socket 同时承载服务端和客户端，服务端可以从同一个 quic.Transport 获取 listener，再把连接交给 http3.Server。如果还承载其他协议，则用 TLS 的 ALPN 结果区分 h3 与其他协议。这个方案的代价是连接关闭顺序、错误传播和 listener 所有权都需要应用明确规定。

服务端与部署边界如何落地

服务端不必因为启用 HTTP/3 就重写 Handler。可以用 http3.Server 保留现有路由，再把证书、UDP 暴露和退出流程接好。若 HTTP/3 入口位于 L4 反向代理之后，要让 Alt-Svc 宣传外部端口，不能只看进程实际监听的端口。

server := &http3.Server{
    Addr:      ":443",
    Handler:   mux,
    TLSConfig: http3.ConfigureTLSConfig(&tls.Config{}), // 配置 h3 ALPN
    Port:      443, // 让 Alt-Svc 使用对外可见端口
}

// 普通 HTTP/1.1 或 HTTP/2 请求可由同一 Handler 继续服务。
if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
    log.Fatal(err) // 只把非正常关闭错误交给进程处理
}

上线前至少确认四件事：证书和 ALPN 是否匹配；入口和防火墙是否放行 UDP；客户端无法使用 HTTP/3 时是否保留 HTTP/2 或 HTTP/1.1；收到退出信号后是否调用带期限的 Shutdown。不要把“支持 HTTP/3”误解成“所有请求都会走 HTTP/3”。

常见问题

只想调用一个 HTTP/3 API，需要自己创建 quic.Transport 吗？

通常不需要。直接配置 http3.Transport 并交给 http.Client，只有本地端口、连接复用或多协议分流成为明确需求时才下沉。

为什么不能只把 HTTP/2 的 Transport 改个协议名？

HTTP/3 的传输基础是 QUIC/UDP，连接、TLS ALPN、流和关闭语义都不同，适配层必须由支持 HTTP/3 的实现负责。

使用自定义 Dial 后最容易漏掉什么？

最常见的是关闭顺序和 socket 所有权。要明确谁关闭 http3.Transport、谁关闭 quic.Transport，并为请求设置 context 超时。