Skip to content
项目

golang-queue/queue has 635 GitHub stars and 50 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 18:45 UTC. Last push 2026-11-14.

这些数字如何统计

可以做什么

  • Supports Circular buffer queues.
  • Integrates with NSQ for real-time distributed messaging.
  • Integrates with NATS for adaptive edge and distributed systems.
  • Integrates with Redis Pub/Sub.

实测星标增长

24小时
0
7天
正在收集历史
15天
正在收集历史
1个月
正在收集历史

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

Queue is a Golang library for spawning and managing a Goroutine pool

开发工具

README.zh-cn.md

原文

队列

CodeQL Run Tests codecov Trivy Security Scan

English | 繁體中文

Queue 是一个 Golang 库,帮助您创建和管理 Goroutines(轻量级线程)池。它允许您高效地并行运行多个任务,利用机器的 CPU 容量。

目录

特性

队列场景

使用环形缓冲区作为默认后端的简单队列服务。

queue01

轻松切换队列服务以使用 NSQ、NATS 或 Redis。

queue02

支持多个生产者和消费者。

queue03

要求

当前分支根据 go.mod 需要 Go 1.26.10 或以上版本;已发布版本的要求可能不同。

安装

安装最新标签版本:

go get github.com/golang-queue/queue@latest

安装开发分支:

go get github.com/golang-queue/queue@main

使用

池的基本用法(使用 Task 函数)

通过调用 QueueTask() 方法,您可以安排任务由池中的工作者(Goroutines)执行。

package main

import (
	"context"
	"fmt"

	"github.com/golang-queue/queue"
)

func main() {
	taskN := 100
	rets := make(chan string, taskN)

	// 初始化队列池
	q := queue.NewPool(5)
	// 关闭服务并通知所有工作者
	// 等待所有作业完成
	defer q.Release()

	// 将任务分配到队列
	for i := 0; i < taskN; i++ {
		if err := q.QueueTask(func(ctx context.Context) error {
			rets <- fmt.Sprintf("Hi Gopher, 处理作业: %02d", i)
			return nil
		}); err != nil {
			panic(err)
		}
	}

	// 等待所有任务完成
	for i := 0; i < taskN; i++ {
		fmt.Println("消息:", <-rets)
	}
}

池的基本用法(使用消息队列)

定义一个新的消息结构并实现 Bytes() 函数来编码消息。使用 WithFn 函数处理来自队列的消息。

package main

import (
	"context"
	"encoding/json"
	"fmt"

	"github.com/golang-queue/queue"
	"github.com/golang-queue/queue/core"
)

type job struct {
	Name    string
	Message string
}

func (j *job) Bytes() []byte {
	b, err := json.Marshal(j)
	if err != nil {
		panic(err)
	}
	return b
}

func main() {
	taskN := 100
	rets := make(chan string, taskN)

	// 初始化队列池
	q := queue.NewPool(5, queue.WithFn(func(ctx context.Context, m core.TaskMessage) error {
		var v job
		if err := json.Unmarshal(m.Payload(), &v); err != nil {
			return err
		}

		rets <- "Hi, " + v.Name + ", " + v.Message
		return nil
	}))
	// 关闭服务并通知所有工作者
	// 等待所有作业完成
	defer q.Release()

	// 将任务分配到队列
	for i := 0; i < taskN; i++ {
		if err := q.Queue(&job{
			Name:    "Gopher",
			Message: fmt.Sprintf("处理作业: %d", i+1),
		}); err != nil {
			panic(err)
		}
	}

	// 等待所有任务完成
	for i := 0; i < taskN; i++ {
		fmt.Println("消息:", <-rets)
	}
}

配置与生命周期

NewPool(n, opts...) 创建内存环形缓冲区并立即开始处理任务。n 小于或等于零时使用 runtime.NumCPU()。NewQueue(opts...) 必须指定 WithWorker(...),缺少 worker 时返回错误,并且需要显式调用 Start()。

QueueTask 用于提交在当前进程执行的 Go 函数。需要序列化消息时,使用 Queue 并实现消息的 Bytes() []byte;处理函数通过 core.TaskMessage.Payload() 读取原始内容。默认环形缓冲区的处理函数由 WithFn 配置,未配置时不会处理消息内容。函数闭包不会被序列化到外部后端。

两种提交方法返回的都是入队错误,不是任务执行结果。任务并发执行,因此完成顺序不保证与提交顺序相同。示例直接提交任务,不需要为每次提交额外创建 goroutine。示例的结果 channel 可容纳全部任务的结果,并假设每个成功入队的任务都会返回一条结果;如果处理函数可能失败,也应返回包含错误的结果,避免调用方一直等待。

选项 默认值 行为
WithQueueSize(n) 0(不设上限) 限制环形缓冲区内等待中的任务数,不含执行中的任务。满载时立即返回 ErrMaxCapacity。
WithWorkerCount(n) runtime.NumCPU() 设置并发执行数;传入 NewPool 时会覆盖其 size 参数。
WithRetryInterval(d) time.Second 无任务时的轮询间隔,必须大于零;这不是任务重试间隔。
WithLogger(logger) 标准 stderr logger 可使用 NewEmptyLogger() 关闭日志。
WithAfterFn(fn) 无 任务成功或失败、统计更新后执行;回调可能同时执行,共享数据需自行同步。

调用 Release() 前,先停止生产者提交任务。默认环形缓冲区在关闭时会拒绝新任务并返回 ErrQueueShutdown,同时处理等待中的任务。Release() 也会等待队列管理的 goroutine 与完成回调结束。关闭过程可能取消执行中任务的 context,不代表每个任务都会成功。外部后端的排空行为取决于各自的 worker 实现。

Wait() 等待的是队列 goroutine 结束,不能用来等待仍在运行的队列变为空闲;这类需求应使用应用程序自己的完成通知。排空期间需保留运行中的 worker:UpdateWorkerCount(0) 会暂停派发,因此有待处理任务时,请先恢复正数再调用 Release()。不要在任务或完成回调内调用 Release(),否则会等待自身结束。

任务重试与超时

将一个 job.AllowOption 传给 QueueTask 或 Queue,即可覆盖任务默认值。以下选项需导入 github.com/golang-queue/queue/job 与 time:

opts := job.AllowOption{
    RetryCount: job.Int64(3),
    RetryDelay: job.Time(200 * time.Millisecond),
    Timeout:    job.Time(5 * time.Second),
}
// 将 opts 作为 q.QueueTask 或 q.Queue 的第二个参数。

默认不重试,超时为 60 分钟。RetryCount: 3 表示处理函数返回错误时,最多执行四次。重试间隔为零时,使用指数退避:从 100 毫秒开始,每次加倍,上限为 10 秒。超时覆盖整个任务,包括重试与等待时间。

处理函数应检查 ctx.Done(),并将 context 传给可取消的 I/O 操作。超时会记录失败,但无法强制停止忽略取消信号的 Go 函数;这类函数可能在 Release() 返回后继续执行。可重试的操作应能安全地重复执行。

统计信息

可通过 SubmittedTasks()、CompletedTasks()、SuccessTasks()、FailureTasks() 与 BusyWorkers() 查看状态。重试属于同一个任务,不会被算作额外提交。请在 Release() 后读取最终统计;并发读取时取得的是快照,不是同一个事务的状态。

开发与验证

在项目根目录运行测试:

go test ./...
go test -race ./...

更多集成细节请参考可运行示例与 worker 接口。外部后端需要另行安装对应的 Go 模块并启动服务;配置方法与消息传递保证请参考下方各后端文档。

使用 NSQ 作为队列

请参阅 NSQ 文档 了解更多详情。

package main

import (
	"context"
	"encoding/json"
	"fmt"

	"github.com/golang-queue/nsq"
	"github.com/golang-queue/queue"
	"github.com/golang-queue/queue/core"
)

type job struct {
	Message string
}

func (j *job) Bytes() []byte {
	b, err := json.Marshal(j)
	if err != nil {
		panic(err)
	}
	return b
}

func main() {
	taskN := 100
	rets := make(chan string, taskN)

	// 定义工作者
	w := nsq.NewWorker(
		nsq.WithAddr("127.0.0.1:4150"),
		nsq.WithTopic("example"),
		nsq.WithChannel("foobar"),
		// 并发作业数量
		nsq.WithMaxInFlight(10),
		nsq.WithRunFunc(func(ctx context.Context, m core.TaskMessage) error {
			var v job
			if err := json.Unmarshal(m.Payload(), &v); err != nil {
				return err
			}

			rets <- v.Message
			return nil
		}),
	)

	// 定义队列
	q := queue.NewPool(
		5,
		queue.WithWorker(w),
	)

	// 将任务分配到队列
	for i := 0; i < taskN; i++ {
		if err := q.Queue(&job{
			Message: fmt.Sprintf("处理作业: %d", i+1),
		}); err != nil {
			panic(err)
		}
	}

	// 等待所有任务完成
	for i := 0; i < taskN; i++ {
		fmt.Println("消息:", <-rets)
	}

	// 关闭服务并通知所有工作者
	q.Release()
}

使用 NATS 作为队列

请参阅 NATS 文档 了解更多详情。

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"

	"github.com/golang-queue/nats"
	"github.com/golang-queue/queue"
	"github.com/golang-queue/queue/core"
)

type job struct {
	Message string
}

func (j *job) Bytes() []byte {
	b, err := json.Marshal(j)
	if err != nil {
		panic(err)
	}
	return b
}

func main() {
	taskN := 100
	rets := make(chan string, taskN)

	// 定义工作者
	w := nats.NewWorker(
		nats.WithAddr("127.0.0.1:4222"),
		nats.WithSubj("example"),
		nats.WithQueue("foobar"),
		nats.WithRunFunc(func(ctx context.Context, m core.TaskMessage) error {
			var v job
			if err := json.Unmarshal(m.Payload(), &v); err != nil {
				return err
			}

			rets <- v.Message
			return nil
		}),
	)

	// 定义队列
	q, err := queue.NewQueue(
		queue.WithWorkerCount(10),
		queue.WithWorker(w),
	)
	if err != nil {
		log.Fatal(err)
	}

	// 启动工作者
	q.Start()

	// 将任务分配到队列
	for i := 0; i < taskN; i++ {
		if err := q.Queue(&job{
			Message: fmt.Sprintf("处理作业: %d", i+1),
		}); err != nil {
			panic(err)
		}
	}

	// 等待所有任务完成
	for i := 0; i < taskN; i++ {
		fmt.Println("消息:", <-rets)
	}

	// 关闭服务并通知所有工作者
	q.Release()
}

使用 Redis (Pub/Sub) 作为队列

请参阅 Redis 文档 了解更多详情。

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"

	"github.com/golang-queue/queue"
	"github.com/golang-queue/queue/core"
	"github.com/golang-queue/redisdb"
)

type job struct {
	Message string
}

func (j *job) Bytes() []byte {
	b, err := json.Marshal(j)
	if err != nil {
		panic(err)
	}
	return b
}

func main() {
	taskN := 100
	rets := make(chan string, taskN)

	// 定义工作者
	w := redisdb.NewWorker(
		redisdb.WithAddr("127.0.0.1:6379"),
		redisdb.WithChannel("foobar"),
		redisdb.WithRunFunc(func(ctx context.Context, m core.TaskMessage) error {
			var v job
			if err := json.Unmarshal(m.Payload(), &v); err != nil {
				return err
			}

			rets <- v.Message
			return nil
		}),
	)

	// 定义队列
	q, err := queue.NewQueue(
		queue.WithWorkerCount(10),
		queue.WithWorker(w),
	)
	if err != nil {
		log.Fatal(err)
	}

	// 启动工作者
	q.Start()

	// 将任务分配到队列
	for i := 0; i < taskN; i++ {
		if err := q.Queue(&job{
			Message: fmt.Sprintf("处理作业: %d", i+1),
		}); err != nil {
			panic(err)
		}
	}

	// 等待所有任务完成
	for i := 0; i < taskN; i++ {
		fmt.Println("消息:", <-rets)
	}

	// 关闭服务并通知所有工作者
	q.Release()
}