Go httptest.NewUnstartedServer 怎么自定义 TLS 配置后再启动

如果 HTTPS 集成测试只需要 Go 自带的测试证书，httptest.NewTLSServer 已经够用；但一旦要在启动前调整 TLS 最低版本、协商协议或客户端认证策略，就应该改用 httptest.NewUnstartedServer。它先创建一个尚未启动的测试服务，等配置完成后再调用 StartTLS。

官方地址：https://pkg.go.dev/net/http/httptest#NewUnstartedServer

这篇只讨论测试服务的配置时机和启动顺序，不把测试证书方案延伸成生产证书部署教程。最重要的一句话是：先改 Server.TLS、EnableHTTP2 或 Config，最后再启动。

先看升级范围：从立即启动改成可配置启动

常见旧写法是调用 NewTLSServer 后立即拿到服务。它内部等价于创建未启动服务再执行 StartTLS，因此调用方没有一个稳定的“启动前窗口”来设置 TLS 策略。

官方文档对 NewUnstartedServer 的说明很明确：它不会启动服务；修改配置后，调用方再选择 Start 或 StartTLS。另外，服务在第一次调用 Client、Start 或 StartTLS 后，就不应继续修改配置。

在启动前设置 TLS 与 HTTP 配置

Server.TLS 负责 TLS 配置，Server.Config 负责 HTTP 服务配置，EnableHTTP2 则必须在启动前设置。不要把这些字段混在一个“启动后再调”的函数里，否则测试偶尔会因为启动时机不同而出现不稳定行为。

package httptesttls

import (
    "crypto/tls"
    "fmt"
    "net/http"
    "net/http/httptest"
    "time"
)

func newTLSTestServer() *httptest.Server {
    handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 处理器只返回测试需要的结果，不把 TLS 配置塞进业务逻辑。
        w.WriteHeader(http.StatusNoContent)
    })

    // 先创建未启动服务，给 TLS 和 HTTP 配置留下明确的修改窗口。
    server := httptest.NewUnstartedServer(handler)

    // 只演示测试策略：要求 TLS 1.3，并限制协商协议为 HTTP/1.1。
    // StartTLS 会把未启动时已有的 TLS 字段带入最终配置。
    server.TLS = &tls.Config{
        MinVersion: tls.VersionTLS13,
        NextProtos: []string{"http/1.1"},
    }

    // HTTP/2 开关也必须在 StartTLS 前设置；本例选择保持关闭。
    server.EnableHTTP2 = false

    // HTTP Server 的超时等配置放在 Config，不要误写到 TLS 配置中。
    server.Config.ReadHeaderTimeout = 2 * time.Second // 2 秒，便于示例直观

    // 最后才启动 TLS；从这里开始不要再改 server.TLS 或 EnableHTTP2。
    server.StartTLS()
    fmt.Println(server.URL)
    return server
}

示例把配置窗口刻意写成连续的几行：创建、修改、启动。这样做的价值不是代码更短，而是让审查者能一眼看出所有配置都发生在 StartTLS 之前。实际项目中可以按需设置超时，但应保留资源关闭责任。

调用 StartTLS 后，用测试客户端访问

StartTLS 会在本地回环接口启动 HTTPS 服务，并设置服务 URL。对于测试服务生成的测试证书，server.Client() 会返回一个已经信任该测试证书的客户端；因此测试代码不需要把 InsecureSkipVerify 打开。

func requestFromTestClient() error {
    server := newTLSTestServer()
    defer server.Close() // httptest.Server 不由 testing 自动创建时，要显式释放监听资源。

    client := server.Client()
    resp, err := client.Get(server.URL + "/health")
    if err != nil {
        return fmt.Errorf("请求 HTTPS 测试服务失败: %w", err)
    }
    defer resp.Body.Close() // 即使只断言状态码，也要关闭响应体。

    if resp.StatusCode != http.StatusNoContent {
        return fmt.Errorf("状态码不符合预期: %s", resp.Status)
    }
    return nil
}

这里的客户端有两个关键点：它是在服务启动后获取的，并且使用了测试服务提供的信任配置。不要把 server.Client() 和 http.DefaultClient 混为一谈；后者不会自动信任 httptest 生成的测试证书。

如果需要自定义证书，先分清服务器配置和客户端信任

“自定义 TLS 配置”不一定等于“替换证书”。如果只要验证最低协议版本、ALPN 或客户端认证策略，可以保留 httptest 的测试证书，只修改 MinVersion、NextProtos 等字段。这样 server.Client() 的默认信任关系仍然清楚。

如果确实要把自有 tls.Certificate 放进 Certificates，就要同步设计客户端的根证书信任方式。此时不要为了让测试通过而全局设置 InsecureSkipVerify: true；应让测试客户端显式信任对应 CA，或者继续采用 httptest 的测试证书。文章的范围只覆盖配置窗口和启动顺序，不把证书生成与生产部署混在一起。

func configureHTTP2(server *httptest.Server) {
    // HTTP/2 选择必须早于 StartTLS；启动完成后再改不会改变已建立的服务配置。
    server.EnableHTTP2 = true
    server.TLS = &tls.Config{
        MinVersion: tls.VersionTLS12,
        NextProtos: []string{"h2", "http/1.1"},
    }
}

如果服务端要测试双向 TLS，还需要在启动前设置 ClientAuth、ClientCAs 等字段，同时让客户端加载对应证书。不要只把服务端开关改成 RequireAndVerifyClientCert，却继续使用没有客户端证书的默认测试客户端。

回归检查：把旧写法迁移成四个明确动作

把原来的 NewTLSServer 替换成可配置方案时，可以按下面的顺序检查：

1. 创建：用 NewUnstartedServer(handler) 得到尚未监听的服务。
2. 配置：先设置 server.TLS、server.EnableHTTP2 和需要的 server.Config 字段。
3. 启动：使用 HTTPS 时调用 server.StartTLS()，不要误调用 Start()。
4. 请求与释放：启动后获取 server.Client()，关闭响应体，测试结束时调用 server.Close()。

最常见的迁移错误有三个：把 TLS 配置写在 StartTLS 后面；用默认 HTTP 客户端访问测试证书；把“测试证书信任”误当成“生产证书验证”。只要把这三组概念拆开，测试代码就会稳定很多。

常见问题

为什么不能直接使用 NewTLSServer 后再修改 TLS？

因为它构造时就已经完成了 TLS 启动，调用方失去了官方文档所说的启动前配置窗口。需要自定义策略时，改用 NewUnstartedServer。

StartTLS 和 Start 应该怎么选？

要测试 HTTPS 就用 StartTLS；只测试明文 HTTP 才用 Start。两者都应在未启动配置完成后调用。

可以把 InsecureSkipVerify 打开吗？

不建议把它当作默认修复。优先使用 server.Client() 信任 httptest 测试证书；如果换成自有证书，就在测试客户端中配置明确的信任根。

总结一下：NewUnstartedServer 解决的是“先配置、后启动”的时机问题，StartTLS 决定服务以 HTTPS 监听，server.Client() 负责在测试中正确接入测试证书。把这三个职责分开，TLS 测试就不需要靠跳过证书校验来凑合。