gitlink-cli/skills/gitlink-shared/references/raw-api-batch.md

Raw API 批处理

当某个 GitLink OpenAPI 尚未封装为 shortcut，但需要重复执行多步请求时，可以使用 api --batch-file 读取 JSON 计划文件。批处理会复用 gitlink-cli 的认证、base_url、输出格式和错误处理，并返回结构化汇总。

示例

{
  "vars": {
    "owner": "Gitlink",
    "repo": "gitlink-cli",
    "issue": "123"
  },
  "requests": [
    {
      "name": "list-open-issues",
      "method": "GET",
      "path": "/v1/{{owner}}/{{repo}}/issues",
      "query": {
        "state": "open",
        "limit": 20
      }
    },
    {
      "name": "comment-issue",
      "method": "POST",
      "path": "/v1/{{owner}}/{{repo}}/issues/{{issue}}/journals",
      "body": {
        "notes": "批处理自动评论"
      }
    }
  ]
}

gitlink-cli api --batch-file plan.json --dry-run
gitlink-cli api --batch-file plan.json --var issue=456
gitlink-cli api --batch-file plan.json --continue-on-error --format json

字段

字段	必填	说明
vars	否	模板变量，支持在 name/path/query/body 字符串中使用 {{name}}
requests	是	请求数组，至少包含一个请求
requests[].name	否	步骤名称，会出现在结果汇总中
requests[].method	是	HTTP 方法，如 GET、POST、PUT、PATCH、DELETE
requests[].path	是	API 路径，可省略开头的 /
requests[].query	否	查询参数对象，值可为字符串、数字、布尔值或数组
requests[].body	否	JSON 请求体，字符串字段会做模板替换

注意事项

• 默认遇到失败会停止；需要继续执行后续步骤时传 --continue-on-error。
• 写入类操作先用 --dry-run 检查渲染后的路径、query 和 body。
• --var key=value 可重复传入，并覆盖计划文件里的同名变量，适合在不同仓库或 Issue 上复用同一计划。
• 批处理模式不能和单次请求的 --body、--body-file、--body-stdin、--query、--header 混用。