first 参数参考

first (GraphQL) / $first (REST) 参数用于限制单次请求返回的记录数。配合 after / $after 参数实现游标分页。

REST：$first

语法

?$first={integer}

传入正整数限制每页条数。传入 -1 返回配置的最大值。

示例

# 每页 5 条
curl "http://localhost:5000/api/Book?\$first=5"

# 返回配置的最大页大小
curl "http://localhost:5000/api/Book?\$first=-1"

# 不指定时使用默认值
curl "http://localhost:5000/api/Book"

行为规则

值	行为
正整数（如 20）	返回最多指定条数的记录
-1	返回配置的 max-page-size
不传	使用 default-page-size（默认 100）
超出 max-page-size	截断为 max-page-size

配置

{
  "runtime": {
    "pagination": {
      "default-page-size": 100,
      "max-page-size": 100000
    }
  }
}

配置项	说明	默认值
default-page-size	未传 $first 时的默认值	100
max-page-size	允许的最大值	100000

与 $after 配合

# 第一页
curl "http://localhost:5000/api/Book?\$first=5"

# 响应包含 nextLink，取出 $after 值
# 第二页
curl "http://localhost:5000/api/Book?\$first=5&\$after=eyJpZCI6NX0="

GraphQL：first

语法

{
  books(first: {integer}) {
    items { ... }
    hasNextPage
    endCursor
  }
}

示例

# 每页 5 条
{
  books(first: 5) {
    items { id title }
    hasNextPage
    endCursor
  }
}

# 返回配置的最大页大小
{
  books(first: -1) {
    items { id title }
  }
}

返回的分页信息

字段	类型	说明
hasNextPage	Boolean	是否还有更多数据
endCursor	String	当前页的游标令牌，作为下一页 after 参数的值

行为规则

值	行为
正整数	返回最多指定条数
-1	返回 max-page-size
不传	使用 default-page-size（默认 100）
超出 max-page-size	截断为 max-page-size

配置建议

场景	default-page-size	max-page-size
移动端、列表页面	20–50	200
Web 后台管理	50–100	1000
数据导出、批量处理	200–500	10000

较小的 default-page-size 可以减少单次请求的数据库负载和网络传输量。max-page-size 防止单次请求拉取海量数据。

REST vs GraphQL 对照

操作	REST	GraphQL
指定条数	?$first=5	first: 5
最大条数	?$first=-1	first: -1
默认值	default-page-size	default-page-size
上限	max-page-size	max-page-size
翻页信息	nextLink URL	hasNextPage + endCursor

下一步

• after — 分页游标参数参考。
• filter — 条件筛选参数参考。
• orderby — 排序参数参考。