Go container/heap 实现定时任务优先队列

Go 用 container/heap 实现定时任务优先队列时，让 Less 按到期时间从早到晚比较，业务代码通过 heap.Push 和 heap.Pop 维护堆。已入队任务改期后调用 heap.Fix；取消任务则可以只标记失效，在它到达堆顶时再清理。

下面做一个只依赖标准库的小程序：按任务 ID 新增或改期，按 ID 取消，再取出某个时刻已经到期的任务。它是内存队列，不是自动执行器，也不承诺任务准点运行。官方文档：https://pkg.go.dev/container/heap；实现源码：https://go.dev/src/container/heap/heap.go。

先定义队列负责什么

以报表、提醒、清理三类任务为例，队列只回答“当前最早的有效任务是谁”和“它是否已经到期”。task 保存 id、due、pos、canceled：due 决定排序，pos 指明当前堆位置，canceled 表示任务已失效。queue 同时保存 items 堆和 live 索引；live 只包含尚未取消、尚未取出的任务。

这两个容器不能混为一谈。items 的长度是物理元素数，live 的长度是有效任务数。延迟删除会让两者暂时不同。这里只让一个调用者顺序操作 queue，后文再说明怎样接入调度循环，不在最小示例里混入锁、线程池和持久化。

用五个方法维护任务堆

taskHeap 实现 Len、Less、Swap、Push、Pop。Less 比较 due，同一时刻再比较 id；这个第二排序键是本例主动选择的规则，不是堆天然稳定。Swap 除了交换指针，还必须同步 pos，否则更新任务时 Fix 可能拿到另一个元素的位置。

接口方法 taskHeap.Push 负责追加，taskHeap.Pop 负责删除切片末尾；业务层应调用 heap.Push、heap.Pop，由标准库完成堆结构调整。直接调用切片的 Push 只会追加，直接调用它的 Pop 只会删尾，都不能替代优先队列操作。Pop 清空被移除槽位，避免底层数组继续保留任务引用。

改期要修复堆，取消可以延迟清理

Put 遇到已有 ID 时，在原对象上更新 due，再按 t.pos 调用 heap.Fix。只改时间不修复结构，会使堆顶不再可信；从队列外保留旧下标也不可靠，因为每次交换都可能改变位置。任务已经取出后 pos 会设为 -1，不能再把它作为有效下标交给 Fix。

Cancel 不去堆中寻找和移除元素，而是设置 canceled 并删除 live 索引。标志不参与 Less，因此不改变堆的排序关系。TakeDue 每次查看堆顶时先清理 canceled，再检查 due：已取消任务即使还没到期，也可以直接回收，因为它已经不会再执行。

取消后复用同一 ID 时，Put 会创建一个新的 task；旧对象仍带 canceled 标记。清理旧对象时不能仅按 ID 删除 live，否则可能误删新对象。示例在取消项分支不删索引，在正常取出分支还使用指针相等保护，明确区分“同名任务”和“同一个对象”。

把队列组合成一个完整小程序

将以下代码保存为 main.go 即可由读者自行运行。日期和任务名都是演示数据，不连接外部服务，也不等待实际分钟数。

package main

import (
    "container/heap"
    "fmt"
    "time"
)

type task struct {
    id string
    due time.Time
    pos int
    canceled bool
}
type taskHeap []*task

func (h taskHeap) Len() int { return len(h) }
func (h taskHeap) Less(i, j int) bool {
    // 同时到期时按ID排序，避免依赖堆的稳定性
    if h[i].due.Equal(h[j].due) { return h[i].id 

按代码语义推导，循环应先打印 report，再打印 reminder，不应打印 cleanup。report 最初排在较后位置，但改期后提前；cleanup 虽然可能仍在切片内，却已无执行资格。这是预期行为说明，不是本文实际运行记录。

构造空堆后逐个 Push 可以保持不变量。若改为一次装入已有切片，应先为每个任务设置正确 pos、建立 live，再调用 heap.Init；不能假设 Init 一定交换每个节点并替你初始化所有下标。示例只开放 Put、Cancel、TakeDue，不把内部 task 指针交给外部随意改字段。

接入真实调度器时补齐哪些能力

这里没有启动 timer，所以 Put 不会让任务自动运行。接入真正的调度器时，可以用一个 goroutine 独占队列，接收新增、改期、取消消息；等待最早有效任务时，如果收到更早任务或当前最早任务改期、取消，需要重新计算等待目标。不要在已睡眠后只更新堆，却让等待仍绑定旧时间。

如果选择加锁，锁应覆盖 live 与 items 的联合修改，而不只保护其中一个。任务取出后再执行回调，避免慢任务占住队列锁。队列不提供崩溃恢复、分布式互斥、执行幂等或重试策略，这些要由上层单独定义。

延迟删除也有空间代价：深埋堆中的取消项可能长期保留。取消量大时，可以在单线程所有者内筛出有效 task，重新设置 pos 并 Init，或改成索引加 heap.Remove 的立即删除方案。这里不把 TakeDue 扫过多个失效元素的总成本说成固定的一次堆操作；积累越多，单次清理的尾延迟越值得关注。

用几个输入判断接口是否用对

堆的切片是完整排好序的吗？

不是。堆只维护足够支持最小元素查询的结构关系，不能直接遍历切片当成按时间排序的列表。需要有序取出时，反复调用 heap.Pop。

改期一定要先 Remove 再 Push 吗？

本例保留了准确 pos，可以直接修改 due 后 Fix。若索引失效或对象已离队，应先修复对象生命周期设计，不能拿旧下标继续更新。

延迟取消为什么不用 Fix？

因为本例的 canceled 不参与比较规则。若后来把它写进 Less，修改标志就可能影响堆性质，原来的“不用 Fix”结论也不再成立。

这个小队列的核心是保持三个约束：排序字段变更后修复堆，Swap 同步位置，有效索引不等于物理切片。标准库接口细节见 heap.Interface 文档，调整实现见 Go 官方源码。