REST API：排序与分页

页面摘要： 使用 :asc 或 :desc 语法对 REST API 结果按一个或多个字段排序，并使用基于页码或基于偏移量的参数进行分页。

对 REST API 发起查询所返回的条目可以进行排序与分页。

TIP

Strapi 利用 qs 库 解析嵌套对象的能力来创建更复杂的查询。

使用 qs 直接生成复杂查询，而不是手动创建。本文档中的示例展示了如何使用 qs。

如果你更喜欢使用在线工具而不是在本地用 qs 生成查询，也可以使用交互式查询构建器。

排序（Sorting）

查询可以接受一个 sort 参数，允许按以下语法对一个或多个字段排序：

  • GET /api/:pluralApiId?sort=value 对 1 个字段排序
  • GET /api/:pluralApiId?sort[0]=value1&sort[1]=value2 对多个字段排序（例如 2 个字段）

排序方向可通过以下方式定义：

  • :asc：升序（默认顺序，可省略）
  • 或 :desc：降序。

示例：使用 2 个字段排序

你可以通过在 sort 数组中传入多个字段来进行多字段排序。

按 Description 与 Name 字段对结果排序。

cURL

curl 'http://localhost:1337/api/restaurants?sort[0]=Description&sort[1]=Name' \
  -H 'Authorization: Bearer <token>'

JavaScript

const qs = require('qs');
const query = qs.stringify({
  sort: ['Description', 'Name'],
}, {
  encodeValuesOnly: true, // 美化 URL
});

await request(`/api/restaurants?${query}`);

响应

{
  "data": [
    {
      "id": 9,
      "documentId": "hgv1vny5cebq2l3czil1rpb3",
      "Name": "BMK Paris Bamako",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ]
      // …
    },
    {
      "id": 8,
      "documentId": "flzc8qrarj19ee0luix8knxn",
      "Name": "Restaurant D",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ]
      // …
    }
    // …
  ],
  "meta": {
    // …
  }
}

示例：使用 2 个字段排序并设置顺序

通过在 sort 参数中为排序字段指定 :asc 或 :desc，你可以获得按特定顺序排列的结果。

按 Description 升序、Name 降序对结果排序。

cURL

curl 'http://localhost:1337/api/restaurants?sort[0]=Description:asc&sort[1]=Name:desc' \
  -H 'Authorization: Bearer <token>'

JavaScript

const qs = require('qs');
const query = qs.stringify({
  sort: ['Description:asc', 'Name:desc'],
}, {
  encodeValuesOnly: true, // 美化 URL
});

await request(`/api/restaurants?${query}`);

响应

{
  "data": [
    {
      "id": 8,
      "documentId": "flzc8qrarj19ee0luix8knxn",
      "Name": "Restaurant D",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ]
      // …
    },
    {
      "id": 9,
      "documentId": "hgv1vny5cebq2l3czil1rpb3",
      "Name": "BMK Paris Bamako",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ]
      // …
    }
    // …
  ],
  "meta": {
    // …
  }
}

分页（Pagination）

查询可以接受 pagination 参数。结果可通过以下方式分页：

  • 按 页码（即指定页码与每页条目数）
  • 或按 偏移量（即指定要跳过的条目数与要返回的条目数）
NOTE

分页方法不可混用。请始终使用 page 配合 pageSize，或者 start 配合 limit。

按页码分页

要按页码对结果分页，请使用以下参数：

参数类型说明默认值
pagination[page]Integer页码1
pagination[pageSize]Integer每页大小25
pagination[withCount]Boolean在响应中附加条目总数与页数True

仅返回第 1 页的 10 条条目。

cURL

curl 'http://localhost:1337/api/articles?pagination[page]=1&pagination[pageSize]=10' \
  -H 'Authorization: Bearer <token>'

JavaScript

const qs = require('qs');
const query = qs.stringify({
  pagination: {
    page: 1,
    pageSize: 10,
  },
}, {
  encodeValuesOnly: true, // 美化 URL
});

await request(`/api/articles?${query}`);

响应

{
  "data": [
    // ...
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "pageCount": 5,
      "total": 48
    }
  }
}

按偏移量分页

要按偏移量对结果分页，请使用以下参数：

参数类型说明默认值
pagination[start]Integer起始值（即要返回的第一条条目）0
pagination[limit]Integer要返回的条目数25
pagination[withCount]Boolean切换是否在响应中显示条目总数true
TIP

pagination[limit] 的默认值与最大值可在 ./config/api.js 文件中通过 api.rest.defaultLimit 与 api.rest.maxLimit 键进行 配置。

使用偏移量仅返回前 10 条条目。

cURL

curl 'http://localhost:1337/api/articles?pagination[start]=0&pagination[limit]=10' \
  -H 'Authorization: Bearer <token>'

JavaScript

const qs = require('qs');
const query = qs.stringify({
  pagination: {
    start: 0,
    limit: 10,
  },
}, {
  encodeValuesOnly: true, // 美化 URL
});

await request(`/api/articles?${query}`);

响应

{
  "data": [
    // ...
  ],
  "meta": {
    "pagination": {
      "start": 0,
      "limit": 10,
      "total": 42
    }
  }
}