pagination

func Walk ¶ added in v0.36.0

func Walk[T any](ctx context.Context, pageSize int, fetch func(ctx context.Context, page int) ([]T, error)) ([]T, error)

Walk 翻页聚合单源：以固定 pageSize 从第 1 页起逐页调 fetch，把全部元素 按页序拼接返回。终止条件是**短页即末页**——某页返回的元素数少于 pageSize （含 0）即为最后一页，此后不再请求。

契约（fetch 一侧）：

• page 从 1 计数，fetch 自行把页码与页长翻译成具体 API 的查询参数；
• fetch 必须**诚实短页**：末页返回实际条数而非凑满 pageSize。上游 API 若在越界页恒返整页，终止条件永不满足，将撞 MaxWalkPages 上限返回 ErrTooManyPages——这是防呆，不是功能；
• 任何一页 fetch 失败立即返回该页错误（带页码上下文），已聚合的部分 不返回——调用方要么拿到全量要么拿到错误，没有半截结果；
• 逐页做 ctx 取消检查，长翻页调用方传值即可获得取消语义。

不做并发预取：上游 API 多数按页序有 token/游标依赖，收益不值得复杂度。 此前 zentao-mini 的 client_* 五个「翻页直到 len<pageSize」循环各写一份 （页长 100/200/500 各异），下沉为一份原语（上游 zentao-mini#22）。

func WalkEach ¶ added in v0.37.0

func WalkEach[T any](budget int, fetch func(page int) ([]T, error), yield func(T) bool) error

WalkEach 按页行走第三方分页 API 的**流式形态**（#211）——与 Walk （翻页聚合单源）同族两个入口：

• Walk：收集全量返回（[]T, error），短页按 pageSize 判定，适合「取 全量再处理」；
• WalkEach：逐条经 yield 回调流出，返回 false **提前终止整个行走** （不是跳页）——「找到即停」的搜索型消费（按 tag 找 release）不必 扫全量；适合大结果集与流式处理。

语义（三家下游独立实现收敛出的取舍）：

• 页号从 1 起、逐页递增；fetch(page) 返回该页条目（回调式而非接口式 ——消费方的 fetch 都是闭包，捕获各自的 SDK client 与 perPage）；
• **短页停止**：len(items) < 上一页长度 即最后一页——不多打一次空页 请求；首页为空直接结束；
• budget 是页数上限（防失控护栏）：fetch 页数达到 budget 仍未走到 短页时返回 ErrBudgetExceeded。budget <= 0 表示无预算（不建议—— 上游恒返整页时行走不终止；对照 Walk 的 MaxWalkPages 硬防呆）；
• yield 返回 false 提前终止，返回 nil（主动终止不是错误）；
• fetch 返回错误中止行走，错误带页码上下文包装（errors.Is 链路保持）；
• 不做并发预取（同 Walk——上游 API 多数按页序有 token/游标依赖）。

fetch/yield 为 nil 返回 ErrNilFetcher / ErrNilYielder。游标制 API 的 行走是另一个域，不在本原语范围。需要 ctx 取消语义的调用方在 fetch / yield 闭包内自行检查（本形态的 fetch 不携带 ctx——它与 Walk 的差别 恰在「行走过程不占用 ctx 生命周期」）。

用法：

var found *Release
err := pagination.WalkEach(50,
    func(page int) ([]*Release, error) { return client.ListReleases(ctx, page, 100) },
    func(r *Release) bool {
        if hasTag(r, want) {
            found = r
            return false // 找到即停
        }
        return true
    },
)