GitLab Issues API按relative_position排序与UI手动排序结果不一致如何解决

REST API 修复方案 #

• 补充必要请求参数：仅指定order_by=relative_position不足以对齐UI排序，需要额外搭配sort=asc参数，完整请求示例：
  {{base_url}}/groups/{{my_group_id}}/issues?order_by=relative_position&sort=asc&include_subgroups=true
• 排查校验规则：
  • 确保你在GitLab UI中至少手动调整过1次议题顺序，未经过手动排序的议题relative_position字段为空，会默认排在列表末尾
  • 如果需要包含子群组议题，必须添加include_subgroups=true参数，否则仅返回当前层级群组的议题，和UI默认展示逻辑不一致
  • 如果要对齐UI默认的「开启中议题」展示效果，可补充state=opened参数过滤已关闭议题
• 版本要求：该能力在GitLab 13.0及以上版本正式生效，低于该版本的自建GitLab实例无法使用该参数实现手动排序

GraphQL 实现方案（更稳定） #

GitLab GraphQL接口对相对排序的支持更稳定，直接通过relativePosition字段排序即可和UI手动排序完全对齐，参考查询示例：

query GroupIssuesSorted($groupFullPath: ID!, $pageSize: Int = 100) {
  group(fullPath: $groupFullPath) {
    issues(
      sort: RELATIVE_POSITION_ASC
      state: opened
      includeSubgroups: true
      first: $pageSize
    ) {
      nodes {
        id
        title
        relativePosition
        iid
        webUrl
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

• 调用说明：
  • 替换$groupFullPath为你的群组完整路径（不是数字ID，是URL中显示的群组路径，比如company-name/dev-team）
  • 如果需要分页，通过返回的endCursor作为下次请求的after参数即可
  • 返回结果的顺序和GitLab UI手动排序结果完全一致

内容的提问来源于stack exchange，提问作者KargWare