Go 有界 Worker Pool:提交、队列与拒绝

Go 有界 Worker Pool:提交、队列与拒绝

Hello,我是小兔大白糖。 读完能说明为什么无界 go func 会炸,以及池化如何把容量合同写进并发。

估计阅读时间:13 分钟

有界 worker pool:提交、队列、Worker
有界 worker pool:提交、队列、Worker · 点击查看 SVG 原图

本文用贴近业务的例子说明常见并发原语,并介绍 ants v2 的用法、典型场景,以及与「原生 WaitGroup + channel / semaphore」的取舍。官方包文档见 pkg.go.dev/github.com/panjf2000/ants/v2。


目录

  1. Goroutine
  2. Channel
  3. 同步原语:WaitGroup、Mutex、Once
  4. 有界并发:带缓冲 channel 与 semaphore
  5. errgroup
  6. Context 与取消
  7. 贴近业务的组合示例
  8. ants v2 协程池
  9. ants 与原生实现对比与选型
  10. 参考链接

1. Goroutine

是什么: Go 里轻量线程,由 runtime 调度,适合 I/O 密集或可并行的独立任务。

现实场景: 批量调外部 HTTP、并发写库(注意连接池与事务边界)、为每个用户请求起一段独立逻辑(仍要限流,见下文)。

// 主 goroutine 不等待子协程时,程序可能直接退出
func main() {
	done := make(chan struct{})
	go func() {
		// 模拟拉取一个订单详情
		_ = fetchOrder("order-1")
		close(done)
	}()
	<-done
}
 
func fetchOrder(id string) string { return id + ":ok" }

注意:

  • go 与调用方并发执行,要「等结果」用 channel、WaitGroup 或 errgroup。
  • 闭包里循环变量要复制进闭包,避免经典 bug(Go 1.22+ 的 for range 语义有调整,仍建议显式 i := i 以兼容老版本思维)。

2. Channel

是什么: goroutine 之间传值 + 同步的管道;未缓冲 = 同步握手,有缓冲 = 异步直到缓冲满。

2.1 无缓冲:必须两端同时准备好

像「递接力棒」:发送方和接收方必须同时在,适合严格一对一交接。

func main() {
	ch := make(chan string)
	go func() {
		ch <- "result" // 会阻塞,直到有人接收
	}()
	fmt.Println(<-ch)
}

2.2 有缓冲:异步排队

// 容量 2:送第三份前,前两个可暂存
q := make(chan int, 2)
q <- 1
q <- 2
fmt.Println(<-q, <-q)

2.3 select:多路等待(超时、取消、多 channel)

现实场景: 等结果,但最多等 2 秒;或同时监听 ctx.Done()。

func doWithTimeout(result chan string) {
	select {
	case v := <-result:
		fmt.Println(v)
	case <-time.After(2 * time.Second):
		fmt.Println("timeout")
	}
}

2.4 关闭与 for range

只应由发送方关闭;接收方用 for v := range ch 读到流结束。

func fanIn() {
	out := make(chan int)
	go func() {
		defer close(out)
		for i := 0; i < 3; i++ {
			out <- i
		}
	}()
	for v := range out {
		fmt.Println(v)
	}
}

2.5 chan struct{} 作「只通知」

不占内存,常用来表示 done / ready。

done := make(chan struct{})
go func() { /* work */; close(done) }()
<-done

3. 同步原语:WaitGroup、Mutex、Once

3.1 sync.WaitGroup:等一批 goroutine 跑完

var wg sync.WaitGroup
for i := 0; i < 3; i++ {
	wg.Add(1)
	go func(id int) {
		defer wg.Done()
		// 并发任务 id
		_ = id
	}(i)
}
wg.Wait()

3.2 sync.Mutex:保护共享写(map、slice、计数器)

var (
	mu  sync.Mutex
	sum int
)
// 多个 goroutine 里:mu.Lock(); sum++; mu.Unlock()

3.3 sync.Once:全局只执行一次(例如单例、一次初始化)

var once sync.Once
once.Do(func() { /* init */ })

4. 有界并发:带缓冲 channel 与 semaphore

问题: 为每个任务 go 一个协程,任务成千上万时会拖垮调度与内存。需要同时最多 N 个在跑。

4.1 用带缓冲 channel 当「许可证」

// 最多 3 个任务同时执行(类似停车场 3 个车位)
const maxConcurrent = 3
tokens := make(chan struct{}, maxConcurrent)
var wg sync.WaitGroup
for i := 0; i < 10; i++ {
	wg.Add(1)
	tokens <- struct{}{} // 取令牌;满则阻塞
	go func(id int) {
		defer func() { <-tokens; wg.Done() }()
		process(id)
	}(i)
}
wg.Wait()

语义: 与 x/sync/semaphore 的 Weighted 类似;N=1 时就是互斥执行的变体(通常直接用 Mutex 更简单)。

4.2 golang.org/x/sync/semaphore(可传 context、支持权重)

现实场景: 每个任务消耗不同资源时可用带权;常见仍是权重 1。

import "golang.org/x/sync/semaphore"
 
sem := semaphore.NewWeighted(4)
if err := sem.Acquire(ctx, 1); err != nil { /* ctx 取消 */ return }
defer sem.Release(1)
// ... 做 CreateChat、HTTP 等 ...

Acquire(ctx,1) 在请求取消时会返回错误,比纯 channel 更适合链路透传 context 的服务端代码(例如你们 batch 建群 / 发消息 Handler)。


5. errgroup

包: golang.org/x/sync/errgroup

用途: 一组子任务,需要都跑完;常希望第一个非 nil 错误后取消兄弟任务的 Context。

g, ctx := errgroup.WithContext(ctx)
g.Go(func() error { return callA(ctx) })
g.Go(func() error { return callB(ctx) })
if err := g.Wait(); err != nil { /* 处理 */ }

和「批量各自成功失败」不同: 你们的 batch 接口是每条独立成功/失败,更常用 WaitGroup + 预分配 results[i],不要因一条失败就 errgroup 全停(除非产品要求整批失败即停)。


6. Context 与取消

现实场景: 客户端断开、父请求超时、上游取消。

  • 在 select 里监听 <-ctx.Done()。
  • I/O 调用的 http.NewRequestWithContext、Mongo 等传 ctx。
  • 与 semaphore.Acquire(ctx,1) 配合,取消时不要再占坑。

7. 贴近业务的组合示例

7.1 限流 + 保序写结果:批量 HTTP 拉取(类似 batch 多 URL)

需求: 100 个 URL,同时最多 5 个在请求,结果下标与入参一致。

func fetchAll(ctx context.Context, urls []string) []fetchResult {
	n := len(urls)
	out := make([]fetchResult, n)
	sem := semaphore.NewWeighted(5)
	var wg sync.WaitGroup
	for i := range urls {
		wg.Add(1)
		go func(i int) {
			defer wg.Done()
			if err := sem.Acquire(ctx, 1); err != nil {
				out[i] = fetchResult{Err: err}
				return
			}
			defer sem.Release(1)
			body, err := httpGet(ctx, urls[i])
			out[i] = fetchResult{Body: body, Err: err}
		}(i)
	}
	wg.Wait()
	return out
}
 
// 示意类型
type fetchResult struct{ Body string; Err error }
 
func httpGet(ctx context.Context, url string) (string, error) {
	// ...
	return "", nil
}

7.2 固定 N 个 worker 从 jobs 取(经典 worker pool)

需求: 任务在 jobs 里排队,永远只跑 workerN 个 goroutine(适合任务持续到达的生产者-消费者模型)。

func runPool(workerN int, jobs []int, process func(int)) {
	jch := make(chan int)
	var wg sync.WaitGroup
	for w := 0; w < workerN; w++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			for j := range jch {
				process(j)
			}
		}()
	}
	for _, j := range jobs {
		jch <- j
	}
	close(jch)
	wg.Wait()
}

8. ants v2 协程池

项目: github.com/panjf2000/ants

一句话: 固定容量复用大量 goroutine 的池;限制并发数、回收/清理、可选 panic 不拖垮进程 等。官方说明:适合「大量创建又销毁的 goroutine」、高并发批处理、HTTP 下异步任务等。

安装:

go get -u github.com/panjf2000/ants/v2

官方包文档(API 全量、Option、Error):
https://pkg.go.dev/github.com/panjf2000/ants/v2

8.1 包级默认池 + Submit(小工具、demo)

import "github.com/panjf2000/ants/v2"
 
func useDefault() {
	_ = ants.Submit(func() { /* 任务 */ })
	// 进程退出前建议 Release 默认池(长驻服务要留意)
}

8.2 自建 Pool:容量确定时(与「最多 N 个同时跑」一致)

pool, err := ants.NewPool(10) // 最多 10 个 worker
if err != nil {
	panic(err)
}
defer pool.Release()
 
var wg sync.WaitGroup
for i := 0; i < 100; i++ {
	i := i
	wg.Add(1)
	_ = pool.Submit(func() {
		defer wg.Done()
		_ = i
		// 业务:调 DB、HTTP
	})
}
wg.Wait()

常用 Option(见 Options):

Option含义(简述)
ants.WithPreAlloc(true)预分配,大容量+长任务时可能减少分配开销
ants.WithNonblocking(true)满则 Submit 不阻塞,返回 ErrPoolOverload
ants.WithMaxBlockingTasks(n)阻塞在 Submit 上的 goroutine 数上限(需细读与 Nonblocking 关系)
ants.WithPanicHandler任务 panic 时集中处理,避免整进程挂
ants.WithExpiryDuration清理闲置过久的 worker 周期

运行时调大池子: pool.Tune(newSize)(注意文档:对 unlimited / 预分配池可能无效)。

释放:Release / ReleaseTimeout / ReleaseContext(ctx)(v2.12+ 的 context 版本适合「优雅退出前等 worker 结束」)。

8.3 PoolWithFunc / NewPoolWithFunc:所有任务共用一个处理函数

适合「任务只是参数不同」(例如 orderID int、URL 字符串),少写闭包分配。

var sum int32
var mu sync.Mutex
 
pool, _ := ants.NewPoolWithFunc(8, func(arg any) {
	id := arg.(int)
	_ = id
	mu.Lock()
	sum++
	mu.Unlock()
})
defer pool.Release()
 
for i := 0; i < 100; i++ {
	_ = pool.Invoke(i) // 交给池里统一 fn
}

泛型版: ants.NewPoolWithFuncGeneric[int](8, func(id int) { ... })(v2.11+),类型安全,少 any 强转。

8.4 MultiPool:多子池 + 负载均衡,减轻单池大锁瓶颈

NewMultiPool:size 是子池个数,sizePerPool 是每个子池容量;RoundRobin 或 LeastTasks 分配任务。适合超大量 Submit 且池成为热点的场景。

// 示意:10 个子池、每个子池容量 runTimes/10、轮询分流
// mp, _ := ants.NewMultiPool(10, runTimes/10, ants.RoundRobin, opts...)
// defer mp.ReleaseTimeout(time.Second)
// mp.Submit(func() { ... })

8.5 顺序不保证(与你们 batch 按 index 回写 的关系)

官方说明: 提交到池中的任务不会保证执行顺序;和「每个任务自己写 results[i]」不冲突——顺序由下标 i 保证,不是由执行先后保证。

实现 batch 时:Submit 闭包内仍写 results[ idx ],不要依赖「先跑完 0 再 1」。

8.6 与你们 Handler 中「semaphore + 每任务一个 go」的类比

  • ants: 复用固定 worker 执行任意 func(),减少无界 go 的调度/栈开销。
  • semaphore + N 个 go 同时跑: 常是「本次请求里最多 5 个并发」,请求结束就结束;不强调跨请求的 goroutine 复用。
  • 若把 ants 当「全局长驻池」: 在 HTTP 入口 里反复 Submit 大量短任务,ants 很合适;一次性 20 条批处理,**原生 WaitGroup+semaphore 往往更简单、依赖更少。见下一节。

9. ants 与原生实现对比与选型

维度原生 WaitGroup + semaphore 或 chan struct{} + goants Pool / Submit
依赖仅标准库 + golang.org/x/sync多一个第三方,需升级、审计
心智每个请求一批任务,与请求生命周期绑定 很直观全局/长驻池,注意 Release、默认池生命周期
复用每次 batch 新建 N 个并发单元(或固定 go 数由 sem 限)跨请求复用 worker,高 QPS 短任务有优势
Context 取消sem.Acquire(ctx,1) 原生友好任务内自行用传入的 ctx;Submit 不替你取消
顺序用 results[i] 与原生相同同样按 i 写结果,不依赖执行顺序
panic要 recover 否则整个进程危险可用 WithPanicHandler 统一兜底
调参改一个 maxConcurrent 常数Tune、MultiPool、Option 多,调优空间大也更复杂

建议:

  • 单接口内 20 条有界并发(如 batch 建群/发消息):WaitGroup + semaphore + 按下标写回,够清晰、好测。
  • 全进程持续涌入海量小任务(如异步通知、流式转码任务投递):ants 或项目自研 worker 池(如本仓库 WORKER_POOL.md)更对口。
  • 若已引入 ants 又希望风格统一,可把批处理改成「向池 Submit、闭包抓 i / arg」;注意 pool.Release 在进程/测试生命周期内只调一次,不要每个 HTTP 请求 new 一个池再 release(除非有明确设计)。

9.1 用 ants 写「同语义的 batch」示意(与 semaphore 版对照)

// 示意:仅表达结构;error 与 pool 错误需按业务补全
func batchWithAnts(ctx context.Context, n int, work func(int) error) []error {
	pool, _ := ants.NewPool(4)
	defer pool.Release()
 
	errs := make([]error, n)
	var emu sync.Mutex
	var wg sync.WaitGroup
	for i := 0; i < n; i++ {
		i := i
		wg.Add(1)
		_ = pool.Submit(func() {
			defer wg.Done()
			err := work(i)
			emu.Lock()
			errs[i] = err
			emu.Unlock()
		})
	}
	wg.Wait()
	return errs
}

对比: semaphore 版是「控制并发」;ants 版还多了「worker 长期复用」。对只跑几十毫秒就结束的 HTTP 里的一次 batch,收益常不明显,却增加全局池的运维成本。


10. 参考链接


文档为通用说明,与具体业务线模块版本无关;ants 具体 API 以 v2.12+ 的 pkg.go.dev 为准。