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  表示无限制（取到 NextCursor 为空为止）
	//   - >0 达到该次数后立即停止，返回 LastCursor 让调用方手动续拉
	// 默认（DefaultPageLimit）= 50 页。
	PageLimit int

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

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

Options 控制 FetchAll 的行为。零值即为合理默认。

type Page ¶

type Page struct {
	Records    []any
	NextCursor string
}

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

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

type Result ¶

type Result struct {
	Records    []any
	HasMore    bool
	LastCursor string
	Pages      int
	Partial    bool
	Err        error
}

Result 是 FetchAll 的最终返回。

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

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