paging

type Fetcher ¶

type Fetcher func(ctx context.Context, cursor string) (Page, error)

Fetcher 是调用方需要实现的"取单页"函数。

• ctx：上游传入的 context，本包负责检查 Done
• cursor：本次请求的 cursor（首次调用传 ""）

返回 Page 或 error。返回 error 时本包会停止翻页并把已累计数据作为 partial 返回给调用方，不直接中断流程。

type Options ¶

type Options struct {
	// PageLimit 最大翻页次数。
	//   - 0  使用 DefaultPageLimit，保持 Options{} 的安全默认语义
	//   - UnlimitedPageLimit 显式表示不限页数（取到 NextCursor 为空为止）
	//   - >0 达到该次数后立即停止，返回 LastCursor 让调用方手动续拉
	PageLimit int

	// InterPageDelay 是页间退避时长。默认 200ms。
	// 仅在抓到非首页时生效（首次调用不 sleep）。
	InterPageDelay time.Duration

	// InitialCursor 是起始 cursor。常用于"接续上次断点"场景。
	// 默认空串表示从头开始。
	InitialCursor string
}

Options 控制 FetchAll 的行为。零值使用默认页数上限和默认页间退避。

type Page ¶

type Page struct {
	Records    []any
	NextCursor string
	// TotalCount 是服务端报告的完整结果总数。未知时保持 nil；FetchAll
	// 不会用 len(Records) 猜测或覆盖它。
	TotalCount *int
}

Page 是单次 fetcher 调用的返回值。

• Records 是本页累计到结果集的数据条目（具体结构由调用方决定）
• NextCursor 为空字符串时表示已无更多页

type Result ¶

type Result struct {
	Records    []any
	HasMore    bool
	LastCursor string
	Pages      int
	Attempts   int
	Complete   bool
	Partial    bool
	StopReason StopReason
	TotalCount *int
	Err        error
}

Result 是 FetchAll 的最终返回。

• Records 已累计的所有数据
• HasMore 触发 PageLimit 或被 fetcher 中断时为 true，可凭 LastCursor 续拉
• LastCursor 最后成功取得的下一页 cursor（仅 HasMore=true 时有意义）
• Pages 成功取得的页数；Attempts 包含失败的最后一次请求
• Complete 仅在服务端明确返回空 NextCursor 时为 true
• Partial 中途遇到错误时为 true，Records 包含错误发生前的数据
• Err 中途错误（调用方应根据业务决定是否报警；本包不主动失败）

func FetchAll(ctx context.Context, fetcher Fetcher, opts Options) Result

type StopReason ¶ added in v1.0.58

type StopReason string

StopReason 是 FetchAll 停止翻页的稳定原因。

const (
	StopComplete    StopReason = "complete"
	StopPageLimit   StopReason = "page_limit"
	StopFetchError  StopReason = "fetch_error"
	StopCanceled    StopReason = "canceled"
	StopCursorCycle StopReason = "cursor_cycle"
)