Go 自定义 DialContext 怎样避免连接 goroutine 泄漏

自定义 http.Transport.DialContext 时，避免连接 goroutine 泄漏的关键不是“再套一层 goroutine”，而是让拨号函数从入口到真正建立连接的每一个可等待环节都使用传入的 context.Context。能取消的等待要在 select 中监听 ctx.Done()；底层拨号本身则应调用 net.Dialer.DialContext，而不是已经失去取消能力的 Dial。

本文把问题缩小到一个小型 HTTP 客户端项目：为 Transport 增加一个可取消的自定义拨号器，并说明为什么“启动后台 goroutine，超时后直接返回”并不能自动消除泄漏。

官方文档：https://pkg.go.dev/net/http#Transport

先分清是哪一个 goroutine 没有退出

看到 goroutine 数量上涨时，不要马上把责任归到 DialContext。一次 HTTP 请求至少可能经历三类等待：Transport 等待连接名额或空闲连接、自定义代码等待信号、底层 DNS/TCP/TLS 拨号。只有第二类和第三类由自定义拨号实现直接负责；连接池排队还要结合 Transport 的连接配置判断。

Transport.DialContext 会与 RoundTrip 并发执行；它的回调签名已经把请求侧的 Context 传进来。一个重要边界是：取消只保证拨号阶段可以尽快结束，连接一旦成功建立，Context 后续过期不会替你关闭这条连接。连接的关闭和响应体释放仍由调用方及 Transport 的连接管理负责。

用一个最小拨号器把 Context 传到底

先写一个只做两件事的拨号器：在进入底层调用前检查已结束的 Context，然后调用 net.Dialer.DialContext。不要为了“监听取消”额外启动 goroutine，因为标准库拨号器已经负责把取消传给网络等待。

package main

import (
	"context"
	"fmt"
	"net"
	"time"
)

// cancelableDialer 只负责把请求 Context 传给标准库拨号器。
type cancelableDialer struct {
	base net.Dialer
}

// DialContext 在真正拨号前拒绝已取消请求，并保持同步返回。
func (d *cancelableDialer) DialContext(ctx context.Context, network, addr string) (net.Conn, error) {
	if err := ctx.Err(); err != nil {
		return nil, err
	}

	// Dialer.DialContext 会在连接尚未建立时响应 ctx 的截止时间或取消。
	return d.base.DialContext(ctx, network, addr)
}

func main() {
	// 本例只展示拨号器的构造，不向外部地址发起网络请求。
	dialer := &cancelableDialer{
		base: net.Dialer{Timeout: 3 * time.Second},
	}
	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
	defer cancel()

	conn, err := dialer.DialContext(ctx, "tcp", "127.0.0.1:1")
	if err != nil {
		fmt.Printf("拨号结束：%v\n", err)
		return
	}
	// 成功建立连接后由调用方负责关闭，避免连接资源悬挂。
	defer conn.Close()
	fmt.Println("连接已建立")
}

这里的 Timeout 是拨号器自己的时间预算，外层 Context 仍然可以更早取消。net.Dialer.DialContext 要求传入非 nil Context；如果 Context 在连接完成前过期，调用返回错误，连接成功后 Context 的过期不会自动关闭连接。

真实项目中不要用示例里的固定端口判断“连接一定失败”，它只是让文章示例不依赖外部服务。要观察取消路径，可以把地址换成你明确控制的测试监听器，并在测试中记录返回的 context.Canceled 或 context.DeadlineExceeded。

自定义等待也必须能被取消

如果拨号前要获得并发名额、读取代理配置或等待内部队列，不能只在方法入口检查一次 ctx.Err()。入口检查只能覆盖“已经取消”的瞬间；正在等待 channel 的代码必须把取消作为并列分支。

type limitedDialer struct {
	base net.Dialer
	gate chan struct{}
}

// DialContext 在占用自定义拨号名额时也遵守请求取消。
func (d *limitedDialer) DialContext(ctx context.Context, network, addr string) (net.Conn, error) {
	select {
	case d.gate 

这个例子把“等待自定义资源”和“等待网络连接”都放进可取消链路。defer 归还名额覆盖了成功、失败和取消三条路径；如果忘记归还，表现可能是后续请求永远等不到名额，看起来也像 goroutine 泄漏。

如果自定义逻辑包含多个阶段，每个阶段都要回答同一个问题：它是否可以在请求取消后返回？不能取消的外部 API 要单独隔离并设置资源上限，而不是假装它已经支持 Context。

把拨号器接入一个可复用的 Transport

Transport 应该像 Client 一样复用，而不是每次请求重新创建。下面把前面的拨号器安装到一个 Transport，并给请求设置独立的总时间预算。代码重点是所有权：返回给 Transport 的连接由 Transport 管理，调用方不能在 DialContext 返回后立刻关闭它。

func newHTTPClient() (*http.Client, *http.Transport) {
	// 共享一个有界拨号器，避免每个请求创建自己的连接池。
	dialer := &limitedDialer{
		base: net.Dialer{Timeout: 5 * time.Second},
		gate: make(chan struct{}, 16),
	}
	tr := http.DefaultTransport.(*http.Transport).Clone()
	tr.DialContext = dialer.DialContext
	tr.MaxIdleConnsPerHost = 8
	tr.IdleConnTimeout = 30 * time.Second

	client := &http.Client{
		Transport: tr,
		Timeout: 10 * time.Second,
	}
	return client, tr
}

func fetch(ctx context.Context, client *http.Client, url string) error {
	// NewRequestWithContext 让请求取消传入 Transport 和 DialContext。
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return err
	}
	resp, err := client.Do(req)
	if err != nil {
		return err
	}
	// 读完并关闭响应体，给 HTTP/1 连接复用机会。
	defer resp.Body.Close()
	_, err = io.Copy(io.Discard, resp.Body)
	return err
}

完整文件还需要导入 io、net/http 等包；这里截取核心函数，重点是 NewRequestWithContext、Transport.DialContext 和响应体关闭三者形成一条资源链。Client.Timeout 是客户端请求的总时间预算，不能替代自定义拨号器对 Context 的正确处理。

在工厂返回 Transport 时，可以由应用生命周期统一调用 CloseIdleConnections 做收尾；不要在每次 fetch 返回时关闭共享 Transport，否则连接池复用和并发行为都会被破坏。

为什么“超时后返回”仍然可能泄漏

最容易误写的适配方式是：旧拨号 API 不支持 Context，于是启动一个 goroutine 执行旧 API，再用 select 等待结果或超时。

type dialResult struct {
	conn net.Conn
	err  error
}

// badAdapter 只能让调用方提前返回，不能取消 legacyDial。
func badAdapter(ctx context.Context, network, addr string) (net.Conn, error) {
	result := make(chan dialResult)
	go func() {
		// legacyDial 如果卡在 DNS、系统调用或第三方库中，可能长期不返回。
		conn, err := legacyDial(network, addr)
		result 

当 Context 先结束时，badAdapter 返回了，但后台 goroutine 仍在执行 legacyDial。因为结果 channel 没有接收者，它完成后还可能卡在发送结果的位置。把 channel 改成容量为 1，可以避免“发送结果”这一步再次阻塞，但底层拨号仍然无法被取消，泄漏风险并没有被根治。

更稳妥的处理顺序是：优先换成支持 Context 的底层 API；若必须使用旧 API，确认它是否提供独立的 Close、Cancel 或 deadline 方法，并把这些控制放到适配器中。若它完全不可取消，就只能接受“调用方提前返回、后台任务可能继续”的事实，同时通过并发上限、生命周期管理和资源回收把影响限定住，不要把该适配器包装成已经安全可取消的 DialContext。

用 trace 和资源计数定位取消是否生效

不要用 goroutine 数量单独证明问题已经解决。可以给请求加 httptrace.ClientTrace，记录进入获取连接、开始拨号、拨号完成和请求错误的时间点；再结合自定义拨号器的进入/退出计数，确认每一次进入是否都有对应退出。

var activeDials atomic.Int64

func tracedDial(ctx context.Context, base net.Dialer, network, addr string) (net.Conn, error) {
	activeDials.Add(1)
	defer activeDials.Add(-1)

	// 计数覆盖取消、网络错误和成功返回三类路径。
	return base.DialContext(ctx, network, addr)
}

func requestContext() (context.Context, context.CancelFunc) {
	// 测试中用短预算触发取消，不把固定耗时当成线上结论。
	return context.WithTimeout(context.Background(), 200*time.Millisecond)
}

这里的计数只能说明自定义函数是否返回，不能证明系统中不存在其他 goroutine。若计数长期不归零，先看它停在哪个底层 API；若计数归零但 goroutine 仍多，再检查请求体、响应体、连接池等待和其他后台工作。

排查时可以按以下顺序做一次单变量检查：

1. 确认请求是用 NewRequestWithContext 创建，取消发生在请求仍可能拨号时。
2. 确认 DialContext 没有偷偷调用旧的 Dial 或启动不可回收的后台任务。
3. 确认自定义 channel、锁和信号等待都有 ctx.Done() 分支。
4. 确认成功返回的 net.Conn 交给 Transport，响应体由请求方及时读取并关闭。
5. 重复相同取消场景，观察进入/退出计数和 goroutine 堆栈，而不是只看一次总数。

把这套规则应用到生产配置

一个安全的自定义拨号器应当满足四个条件：回调同步返回；所有自定义等待都能被 Context 取消；底层网络 API 接收同一个 Context；成功连接的所有权和关闭责任清晰。Transport 文档还说明，Transport 是低层 HTTP 原语，适合复用并发使用，因此不要通过频繁重建 Client 或 Transport 来“清理”泄漏。

如果问题只发生在 HTTPS，要检查是否设置了 DialTLSContext。当它被设置时，HTTPS 请求不会使用普通的 Dial 或 DialContext 钩子；把取消逻辑写在错误的钩子里，可能导致测试 HTTP 有效、生产 HTTPS 却没有走到预期代码。

最后记住边界：Context 控制的是调用方发起的工作和拨号阶段，不会替第三方库凭空创造取消能力，也不会自动替你关闭已经成功建立的连接。先让底层 API 具备可取消语义，再把它接入 Transport，通常比在外围增加 goroutine 更可靠。

DialContext 里可以启动 goroutine 吗？

可以，但必须有明确的退出、取消和结果回收路径。若后台任务调用的 API 无法取消，调用方超时返回并不等于任务结束；这类实现不能声称已经解决 goroutine 泄漏。

入口先判断一次 ctx.Err() 就够了吗？

不够。正在等待 channel、锁、队列或网络连接时仍可能发生取消，等待点必须把 ctx.Done() 作为可选分支。

拨号成功后 Context 取消会自动关闭连接吗？

不会。官方 net.Dialer.DialContext 的 Context 主要约束连接尚未完成的拨号阶段；成功连接后的关闭需要由连接所有者负责。

为什么请求已经超时，goroutine 还没马上消失？

底层系统调用、DNS 实现、第三方拨号库或其他后台任务可能还没返回。应通过堆栈和资源计数定位具体等待点，不要把“请求函数返回”当作“所有工作结束”。

相关资料：https://pkg.go.dev/net/http#Transport、https://pkg.go.dev/net#Dialer.DialContext、https://pkg.go.dev/context。把取消信号一路传到真正能响应它的等待点，才是自定义 DialContext 避免连接 goroutine 泄漏的核心。