Go 项目怎样为 HTTP/3 客户端划分可选依赖

Go 项目可以把 HTTP/3 实现放在适配器里，对业务只暴露 http.Client 或 http.RoundTripper，再用构建标签控制实现是否参与编译。但若要让基础模块连第三方模块要求都不承担，仅有标签或运行时开关不够，通常还需把 HTTP/3 适配器放进独立模块，并由启用它的应用负责组装。

一个容易误判的场景是：配置里已经关闭 HTTP/3，构建或整理依赖时却仍然遇到 quic-go 的工具链要求。这个现象不一定说明开关失效，可能只是“运行时可选”被误当成“模块依赖可选”。下面用一个小型客户端工厂逐层说明。

quic-go 官方客户端说明：https://quic-go.net/docs/http3/client/；API：https://pkg.go.dev/github.com/quic-go/quic-go/http3；Go 模块规则：https://go.dev/ref/mod。

先确认关闭的究竟是哪一层

运行时关闭意味着不选择 HTTP/3 transport，源码 import 仍可能存在；编译时关闭意味着该实现文件不参与当前构建；模块隔离则要求基础模块不依赖该第三方模块。这三种目标应分别写清楚。

用 RoundTripper 接住实现，不让业务绑定专有类型

quic-go 的 http3.Transport 实现标准 http.RoundTripper，可安装到 http.Client.Transport。业务层因此可以继续通过 http.Client 发请求，而不是把 quic-go 的连接类型、配置类型传播到所有业务包。

RoundTripper 表示一次 HTTP 事务，不负责整个 Client 的所有策略，也要求实现可被多个 goroutine 并发使用。代理支持、连接关闭和特定协议能力仍由实际实现决定，接口相同不代表行为完全相同。

建议把 业务请求、http.Client、RoundTripper 放在调用边界，把 标准 Transport 和 HTTP/3 适配器 放在实现边界，专有依赖只出现在后者。

为什么配置开关没有消除依赖要求

如果同一个普通 Go 文件直接 import http3，即使程序启动时判断 enabled 为 false，编译阶段仍要解析这个 import。不要用运行时 if 分支来证明构建已经摆脱第三方依赖。

对同一模块，构建标签可以限制本次参与编译的文件；但 Go 模块文档明确指出，go mod tidy 按几乎所有构建标签都启用的方式加载包，自定义标签下的文件也会被考虑，ignore 标签有特殊例外。因此，不启用标签进行 build，与 tidy 是否保留 require 是不同结果。

这也解释了“默认二进制没编入 HTTP/3 包，但 go.mod 仍保留 quic-go”的情况：可以是设计所允许的状态，不必通过删除 go.sum 或清空依赖缓存来处理。

用两份互斥文件控制编译入口

以下三个文件放在同一个 client 包目录。它们组成库包，不是独立 main 程序。工厂返回客户端与清理函数；清理由组装层负责，业务包不需要认识第三方类型。标准分支只是简单配置示例，不替代完整生产网络策略。

client.go

package client

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

// New 在初始化时选择实现，不在请求失败后自动切换协议。
func New(mode string) (*http.Client, func() error, error) {
    switch mode {
    case "standard":
        tr := &http.Transport{
            Proxy: http.ProxyFromEnvironment,
            ForceAttemptHTTP2: true,
            IdleConnTimeout: 90 * time.Second,
        }
        cleanup := func() error {
            // 调用方应先停止请求并等待处理完成。
            tr.CloseIdleConnections()
            return nil
        }
        return &http.Client{
            Transport: tr,
            Timeout: 10 * time.Second,
        }, cleanup, nil
    case "h3":
        return newH3()
    default:
        return nil, nil, fmt.Errorf("未知客户端模式：%q", mode)
    }
}

h3_enabled.go

//go:build http3client

package client

import (
    "net/http"
    "time"

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

// 编译期确认适配器提供标准事务接口。
var _ http.RoundTripper = (*http3.Transport)(nil)

func newH3() (*http.Client, func() error, error) {
    tr := &http3.Transport{}
    // Close 由初始化调用方在停止使用后统一调用。
    return &http.Client{
        Transport: tr,
        Timeout: 10 * time.Second,
    }, tr.Close, nil
}

h3_disabled.go

//go:build !http3client

package client

import (
    "errors"
    "net/http"
)

// 不含标签的构建遇到显式 h3 选择，直接返回可理解的错误。
func newH3() (*http.Client, func() error, error) {
    return nil, nil, errors.New("本次构建未启用 HTTP/3 客户端")
}

构建约束必须位于文件顶部，和 package 行留空行。两份文件互斥，避免 newH3 重复定义。New("h3") 在默认构建中明确失败，而不是悄悄发送另一种协议。成功得到客户端后复用它；每个响应 Body 仍由请求调用方关闭。HTTP/3 的 Close 之后 transport 不可继续使用，不能把它当成普通关闭空闲连接的同义词。

工具链兼容性仍要跟实际选定版本走

这里的 HTTP/3 文件使用 http3.Transport API。以官方仓库 v0.63.0 的 go.mod 为例，其 go 指令为 go 1.26.0，不能把这份实现默认承诺给更老的工具链。这个版本只是可追溯示例，不是“永远最新”或“所有项目推荐版本”；采用其他版本时重新读取其模块要求与 API。

Go 的工具链选择还可能受 GOTOOLCHAIN 和当前模块要求影响。不要因构建标签默认关闭，就宣称同一 go.mod 对旧工具链必然兼容。基础模块若确实需要维持较低工具链要求，应把适配器拆成独立模块：核心模块 只依赖标准接口；HTTP/3 模块 依赖核心模块与 quic-go；启用应用 负责选择和连接实现。默认应用不导入适配器，才有清楚的模块级隔离。

怎样核对隔离结果，而不是只看开关

对接受同一模块保留依赖的方案，读者可用默认与带标签的构建分别核对入口；对模块级可选方案，应在基础模块独立执行相应操作，不要仅在同时包含全部模块的工作区里下结论。

# 在示例模块根目录查看当前工具版本。
go version
# 固定示例依赖版本，需满足其工具链要求。
go get github.com/quic-go/quic-go@v0.63.0
# 默认构建排除 HTTP/3 实现文件。
go build ./...
# 显式开启后编译 HTTP/3 适配器。
go build -tags=http3client ./...
# 查看两个构建配置实际涉及的包依赖。
go list -deps ./...
go list -tags=http3client -deps ./...

这些是提供给读者的命令，不是本文已执行的测试。判断时应查看自己的输出：默认包图是否包含 http3、带标签是否包含适配器、基础模块是否仍声明相应 require。go list 的包依赖结果与 go.mod 的模块要求不可互相替代。

接口隔离能保证 HTTP/3 连接成功吗？不能，服务端支持、网络可达性及证书配置是另外的集成条件。本文没有连接目标站点，也没有通过关闭证书校验来解决兼容性。

失败后可以自动回退吗？示例不做回退。请求是否已发送、请求体是否可重放以及操作是否允许重复，需要单独设计，不能无条件重试写请求。

每个请求都创建 transport 吗？不建议把工厂当一次请求工具。应在适当生命周期内复用客户端，关闭响应体，并由唯一拥有者在停止使用后执行清理。

把 HTTP/3 做成可选能力，先选对“可选”的层级：标准接口降低业务耦合，构建文件控制编译实现，独立模块控制依赖要求。三者组合起来才不会把配置关闭、编译排除与兼容性混为一谈。