Documentation
¶
Overview ¶
Package poll 提供「带单调游标的长轮询批量拉取」循环原语:拉一批 → 逐项处理 → 游标前进 → 再拉,失败按 retry 的退避公式续拉,直到 ctx 取消。
收编自 IM / 消息平台收消息循环反复被复制的那一份形状(长轮询 + 游标 + 批量 + 失败续拉),把四个会各自漂移的语义一次钉死:
- 游标只前进——非空批次必须带回不同游标,否则 ErrCursorStuck 当场返回
- 处理完才推进——本批处理过才推进游标,语义恒为 at-least-once(不会「游标跑了、 消息没处理」)
- 失败退避可指数可抖动——复用 retry.Config(含 DelayHint 服务端建议), 不再是手写固定几秒;不可续拉的错误带错误返回、不空转
- 单项 panic 不杀循环——每项经 async.RunSafeCtx 就地收编成 *async.PanicError, 同时汇报全局 PanicHandler;循环存活
- 毒丸有出口——死信档(HandleRetries>0 + DeadLetter,#231):可续拉的失败 就地重试至多 N 次后交钩子出档、批次继续,毒丸不再绑架整条游标;缺省不开档, 首项失败即停批回退(Retryable 门判死的错误开档也带错返回,#226 语义不变)
与相邻原语的分工 ¶
- retry.Do/DoValue:**有界**的「动作重试」——N 次之内把一件事做成,做不成返回错误。
- retry.Poll:**有界**的「条件轮询」——到 deadline 为止等条件成立。
- loop.Run:**定时**驱动的周期任务(心跳/清理/对账)。
- poll.RunCursor:**数据**驱动的常驻循环——只要 ctx 还活着就一直拉,游标是它 唯一的进度凭据,且这个凭据由库负责只进不退。
需要「N 次之内把一批数据处理完」用 retry;需要「一直收消息」用本包。
用法 ¶
cfg := poll.Config{
ErrorBackoff: retry.Config{
Delay: 200 * time.Millisecond,
Exponential: true,
MaxDelay: 5 * time.Second,
JitterRatio: 0.2, // 多实例同时撞故障时打散重试
},
IdleDelay: 0, // 服务端 hold 的自适应长轮询;不 hold 的接口必须给正值
OnAdvance: store.Save,
}
final, err := poll.RunCursor(ctx, cfg, cursor, fetchBatch, handleOne)
游标持久化由调用方注入(OnAdvance)——各消费方的存储不同,库只负责**时机** (先落盘成功、再在库内算作推进)。进程退出时用 RunCursor 的返回值做最后一次 兜底持久化。
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrCursorStuck = errors.New("poll: 拉取返回非空批次但游标未前进")
ErrCursorStuck 拉取返回了**非空批次**,却没让游标前进。
这不是「暂时没数据」,而是调用方 fetch 实现的契约违反:下一轮会用同一个游标 拉到同一批,于是同一批被无限重复处理(同时把 CPU 打满)。它不会自愈, 故 RunCursor 带着本错误**返回**而不是退避重试——让它在第一次发生时就可见。 errors.Is 可辨(错误串里带当前游标与本批条数)。
Functions ¶
func RunCursor ¶
func RunCursor[T any]( ctx context.Context, cfg Config, from string, fetch func(ctx context.Context, cursor string) (items []T, next string, err error), handle func(ctx context.Context, item T) error, ) (string, error)
RunCursor 运行「带单调游标的长轮询批量拉取」循环,直到 ctx 取消或发生不可续拉的错误。
返回**当前游标**与退出原因:ctx 取消 ⇒ ctx.Err();不可续拉 ⇒ 该错误; 契约违反 ⇒ ErrCursorStuck。调用方拿返回的游标做关机时的最后一次持久化。
为什么需要它 ¶
IM / 消息平台的收消息循环是同一个形状,逐平台复制:带游标拉一批 → 出错等固定 几秒 → 推进游标并持久化 → 逐条处理。复制出来的副本在三个地方各自漂移: 退避是手写的固定值(无指数、无抖动 ⇒ 两个平台同时撞故障会同步重试,把下游 按同一节奏再打一遍);游标推进时机各写各的(先推进后处理 = 崩溃丢消息,先处理 后推进 = 崩溃重复投递,两版混在生产里);批内一条坏数据 panic 打死整个循环。
本原语把这四件事钉死成一份实现:
- **游标只前进**——非空批次必须带回不同游标(否则 ErrCursorStuck);
- **处理完才推进**——本批 handle 全过(或按 AdvanceOnItemError 落账)才推进 游标,语义恒为 at-least-once,不会出现「游标跑了、消息没处理」;
- **失败退避可指数可抖动**——复用 retry 的退避公式与 DelayHint,不再是固定 几秒;不可续拉的错误直接带错误返回,不空转;
- **单项 panic 不杀循环**——每项经 async.RunSafeCtx 就地收编成 *PanicError (同时汇报全局 PanicHandler),循环存活、按失败档处理该项。
语义契约 ¶
- fetch 同步执行,ctx 原样传入(长轮询要能被取消);fetch panic 收编后当作 一次可续拉失败。
- fetch 返回 **0 项**:按 IdleDelay 等待后再拉——游标被服务端推进也照等 (推进的只是读位置,本轮同样没有产出数据,见 IdleDelay 说明); next 非空且与当前不同则视为服务端把游标推到了当前位置,照常推进。
- fetch 返回 **非空批**:游标必须前进(见 ErrCursorStuck)。
- handle 逐项**串行**调用(不并发:消息处理通常有顺序语义),每项独立收编 panic。
- 缺省档下某一项失败即**停止处理本批**(后面的项留到重拉时再处理,不会被跳过)、 不推进游标、按退避重拉。
- 死信档(HandleRetries>0,#231):单项失败先过 Retryable 门(判 false 仍带错 返回,#226 语义不变),可续拉的就地重试至多 HandleRetries 次,仍败交 DeadLetter 出档、批次继续;钩子失败同样过门(可续拉则退避重拉同一批)。
- 退避等待期间 ctx 取消 ⇒ 立即返回(不睡满)。
- 续拉失败次数在成功一轮后归零(退避不会一路涨到 MaxDelay 卡死)。
用法 ¶
cursor, _ := store.Load(ctx) // 各自存储
final, err := poll.RunCursor(ctx, poll.Config{
ErrorBackoff: retry.Config{Delay: 200 * time.Millisecond, Exponential: true, MaxDelay: 5 * time.Second, JitterRatio: 0.2},
IdleDelay: 0, // 服务端 hold 的自适应长轮询
OnAdvance: store.Save,
}, cursor, fetchBatch, handleOne)
if err != nil && !errors.Is(err, context.Canceled) {
log.Error("收消息循环退出", logx.ErrKey, err)
// (logx.ErrKey 为 oekit/logx 的错误字段常量——错误字段名统一走该常量,
// 禁止手写 "err" 字面量,消费方仓 AGENTS 同款红线,#288。)
}
Types ¶
type Config ¶
type Config struct {
// ErrorBackoff 失败续拉的退避配置,复用 retry.Config 的**全部**口径:
// Delay/Linear/Exponential/MaxDelay/Jitter/JitterRatio/DelayHint。
//
// 唯一不参与的是 Attempts——本原语是常驻循环,失败会一直续拉到 ctx 取消,
// 「要不要继续」由 Retryable 而非次数决定(见 Retryable 字段说明)。
ErrorBackoff retry.Config
// Retryable 判定循环中的错误是否可续拉——fetch 错误、handle 单项错误、
// OnAdvance 错误**三处都过这道门**;nil = 全部可续拉。
// 返回 false 的错误会让 RunCursor **带着该错误返回**(如鉴权失效、游标被服务端
// 作废、毒丸消息、持久化存储被删——这类错误重试一万次也不会好,只会把日志
// 刷满;尤其 OnAdvance 持续失败时没有这道门就只剩退避续拉,契约承诺的逃生门
// 永远不触发)。
// 优先级高于 ErrorBackoff.Retryable(这里的是循环级口径)。
Retryable func(error) bool
// IdleDelay 空批等待。拉取成功但返回 0 项时,等这么久再拉下一批(#229:
// 无论游标是否被服务端推进)。游标推进的只是读位置,本轮同样没有产出数据,
// 按空闲等待无害;且「空批推游标」的形态下每轮游标都在变,若按「推进即有
// 进展」豁免等待,不 hold 的服务端会退化成忙轮询——正是本字段要防的失效形态。
//
// <=0 = 立即再拉,正确性上只适用于**服务端 hold**(长轮询:请求会挂到有数据或
// 超时才返回)的接口。服务端不 hold 的接口必须给正值,否则就是忙轮询——
// 这一点没有安全的缺省值:hold 与不 hold 用同一个数字必然有一边是错的。
IdleDelay time.Duration
// AdvanceOnItemError 单项处理失败时**仍然**推进游标。
//
// false(缺省)= 本批不推进游标,退避后重拉同一批。语义是 at-least-once:
// 已处理过的项会再处理一次(handle 须按项幂等),未处理的项不会被跳过。
// 这是缺省档——丢消息比重复处理难查得多。
//
// true = 失败项由 handle 自己落账(死信表/重试表),库处理后继续、整批处理完
// 推进游标。本档要求 handle 承担落账责任:库不会把该项错误再交给任何人。
// 选本档的理由只能是「重复投递的代价高于漏处理」,例如平台侧消息 id 不可去重。
//
// 与死信档(HandleRetries>0,#231)同开时以死信档为准:失败项先就地重试、
// 预算耗尽走 DeadLetter 出档,本档「handle 自己落账」的口径被其覆盖。
AdvanceOnItemError bool
// OnAdvance 游标推进回调:库在**推进之后**同步调用一次,供调用方持久化
// (各消费方的存储不同,库不碰)。返回错误 ⇒ 视为本轮失败:游标退回旧值、
// 按 ErrorBackoff 退避后重拉同一批——持久化不上却继续前进,重启后就会从
// 一个从未落盘的游标继续,等于凭记忆跳读。
// nil = 不做持久化(内存游标,进程重启即重置)。
OnAdvance func(ctx context.Context, cursor string) error
// HandleRetries 单条 item 的 handle 就地重试上限(缺省 0 = 不开死信档:
// 首项失败即停批回退,行为与没有本字段时完全一致)。
//
// 开档后单项失败不再立即停批:可续拉的错误就地重试(不退避——毒丸的出口
// 是出档而非时间)至多 HandleRetries 次,仍败则交 DeadLetter 出档、批次
// 继续——毒丸不再绑架整条游标(#231)。
//
// 与 Retryable 正交且门优先(#226):门答「这个错误还值得重试吗」,死信档
// 答「这条消息还值得留在队列里吗」。任一次失败被门判 false 仍即刻带错返回
// ——开档不放行调用方显式判死的错误(如鉴权失效),否则故障期会把每条
// 消息逐个出档丢掉。
//
// >0 必须同时配置 DeadLetter(RunCursor 入口 panic 校验):出档没有接收方
// 等于静默丢消息,那是比 panic 更坏的失败形态。
HandleRetries int
// DeadLetter 毒丸出档钩子:重试预算耗尽后拿到该 item(以 any 传入——Config
// 保持非泛型、不改既有调用方签名,钩子内断言回自身类型)、最后一次错误与
// 已试次数(含首次:HandleRetries=2 ⇒ attempts=3)。
//
// 返回 nil 即视为钩子已接管该消息(落死信库/告警由钩子负责,库不再保证
// 重投);返回错误则死信本身失败,与其他失败路径同口径过 Retryable 门——
// 可续拉按 ErrorBackoff 退避后重拉同一批(该项下一轮重新入档重试,钩子须
// 可重入),不可续拉带错返回。
//
// 游标语义不变:钩子本身不推游标,出档项是否再来由既有 advance 语义决定
// (OnAdvance 失败回退、进程在 advance 前崩溃——at-least-once 形态下毒丸
// 会在下一轮再次入档)。持久化死信是调用方的决定,库只保证钩子被调用到。
// nil = 钩子未配置(HandleRetries>0 时不允许)。
DeadLetter func(ctx context.Context, item any, err error, attempts int) error
}
Config 长轮询批量拉取循环的参数。零值可用(立即拉取、失败固定零退避、空批立即重拉)。