Gitlink
/
gitlink-cli
0
0
Fork 49
Code Issues Pull Requests 11 Packages Projects Releases 10 Wiki Activity
gitlink-cli/doc/changes/list-all-pagination.md

5.9 KiB
Raw Blame History

list 命令 --all 自动翻页

背景

issue +list、pr +list、branch +list、release +list 此前一次只能取一页， 用户或 AI Agent 想拿到全量列表必须手动循环 --page。代码中虽有 PaginateAll 翻页助手，但它只识别 data 包裹键；而 GitLink 生产 API 的列表响应实际用 资源名包裹数组（如 {"total_count":N,"issues":[...]}、"pulls"、"branches"、 "releases"），导致该助手在真实端点上退化为「单对象」返回，从未被任何命令使用。

变更内容

  • internal/client：翻页助手对齐生产响应形状
    • 新增 PaginateAllKey(path, params, listKey)：按指定资源键提取数组； listKey 为空时自动探测（顶层数组 / data 包裹 / 唯一数组字段）。
    • 遵循 total_count：达到总数即停止；另设最大页数护栏，防止 忽略 page 参数的端点造成死循环。
    • PaginateAll 保持原签名，委托给 PaginateAllKey。
  • 十九个分页 list 命令新增 --all 布尔参数（默认 false）：
    • issue +list --all（合并结果同样应用 number/database_id 规范化）
    • pr +list --all、branch +list --all、release +list --all
    • milestone +list --all、org +list --all、repo +list --all
    • search +repos --all、search +users --all
    • label +list --all、member +list --all、webhook +list --all
    • issue +comments --all（新增子命令，见下）
    • tag +list --all、commit +list --all（新增命令组，见下）
    • repo +watchers/+stargazers/+forks --all、org +members --all （资源键 organization_users，生产实测 gitlink 组织 71 名成员全量合并）
    • org +repos --all（新增子命令：组织仓库列表 /organizations/:name/projects，此前只能裸 api 访问； 生产实测 gitlink 组织 28 个仓库全量合并）
    • 对应资源键：issues/pulls/branches/releases/milestones/ organizations/projects/users/issue_tags/collaborators/webhooks （均生产实测确认）
    • 输出与单页响应同构：{"total_count": N, "<资源名>": [...]}。
  • 总数字段兼容 total_count 与 count（如 /users/:login/projects）。
  • 修复三个既有分页语义缺口（均生产实测确认端点本身分页）：
    • label +list 完全没有 --page/--limit（端点实际返回 total_count），现已补齐；
    • member +list 既无分页又走遗留路径（非管理员直接 403），现改走 /v1/:owner/:repo/collaborators（支持分页且普通成员可读）；
    • webhook +list 完全没有 --page/--limit（探针实测：建 3 个 webhook 后 page=2&limit=1 返回第二条，确认端点分页），现已补齐；
    • repo +watchers/+stargazers 完全没有分页 flag（端点实测分页， 总数键 count，forgeplus watchers 264 / stargazers 577），现已补齐。
  • 新增 tag +list 命令组：平台暴露分页的 /v1/:owner/:repo/tags 端点（轻量 tag 与 release 不同），但 CLI 此前完全没有 tag 命令； 生产实测 forgeplus 16 个 tag 分页与 --all 合并均通过。
  • 新增 commit +list 命令组：分页的 /v1/:owner/:repo/commits 端点此前只能通过裸 api 命令访问；支持 --ref 指定分支/tag/SHA （映射 sha 参数，生产实测 forgeplus 6762 commits、develop 5346）； 另新增 commit +view --sha 单提交详情（v1 无此端点，走遗留 /api/:owner/:repo/commits/:sha，生产实测含 diff 统计与文件列表）。
  • 新增 repo +forks：分页的 forks 列表（总数键 count， 生产实测 forgeplus 77 个 fork 全量合并）；此前只有 fork 创建命令。
  • 修复翻页助手服务端封顶 limit 丢数据 bug：当端点把请求的 limit 封顶（如请求 100 每页只返 20）时，旧逻辑因「页内条数 < limit」提前 终止只拿到首页；现已知 total 时以 total 为准（watchers 264 条全量 合并生产实测），新增回归单测。
  • 新增 issue +comments 子命令（对标 gh issue view --comments）： 此前 CLI 只能发评论（issue +comment）无法读评论流，Agent 无法获取 issue 讨论上下文；现接 /v1/:owner/:repo/issues/:number/journals （资源键 journals，生产实测分页 + --all 合并通过）， 复用 --number/--id 语义。
  • 新增 pr +commits 子命令：读 PR 的提交列表（commits 端点）； 生产实测该端点同样忽略 page/limit 始终全量，故不暴露分页 flag。
  • 新增 pr +comments 子命令：读 PR 评论流 （/v1/:owner/:repo/pulls/:number/journals）。生产实测该端点 忽略 page/limit 始终返回全量，故不暴露分页 flag（避免假分页语义）。
  • 未加 --all 的 list 端点均经生产验证为非分页或未部署： licenses/ignores 返回全量数组；pm/pipelines 404 未部署； pipeline +runs 用 total_data 非标准包裹；dataset 端点未部署（平台 issue #144255）。
  • 中英文 i18n 新增 flag.all 文案。

命令示例

# 拉取仓库全部 open issue（自动翻页合并）
gitlink-cli issue +list --state open --all --format json

# 全部分支 / 全部 PR / 全部 release / 全部里程碑
gitlink-cli branch +list --all
gitlink-cli pr +list --state all --all
gitlink-cli release +list --all
gitlink-cli milestone +list --all

# 全部组织 / 某用户全部仓库 / 搜索结果全量
gitlink-cli org +list --all
gitlink-cli repo +list --user Taoyouce --all
gitlink-cli search +repos --keyword gitlink --all

测试

  • internal/client/pagination_test.go：资源键包裹多页合并、total_count 截断（模拟忽略 page 的异常端点）、data 包裹、唯一数组字段自动探测、 单对象回退、指定键缺失回退，共 6 个用例。
  • shortcuts/issue：--all 端到端用例验证按页请求序列与合并。
  • go test ./...、go vet、gofmt 全部通过。