所有返回资源列表的 NueForm API 端点都支持基于页码的分页。本指南介绍查询参数、响应格式以及遍历所有结果的模式。
查询参数
使用两个查询参数控制分页：
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
page | integer | 1 | 要获取的页码（从 1 开始）。 |
per_page | integer | 20 | 每页的项目数。最小值：1，最大值：100。 |
如果 per_page 超过 100，API 会自动将其限制为 100。小于 1 的值默认为 1。
请求示例
GET
/api/v1/forms?page=2&per_page=25curl
curl -X GET "https://app.nueform.com/api/v1/forms?page=2&per_page=25" \
-H "Authorization: Bearer nf_your_api_key_here"
响应格式
分页响应在 data 数组之外还包含一个 meta 对象：
json
{
"data": [
{
"id": "clx1abc2d3e4f5g6h7i8j9k0",
"title": "Customer Feedback",
"status": "published",
"created_at": "2026-01-15T09:30:00.000Z"
},
{
"id": "clx2def3g4h5i6j7k8l9m0n1",
"title": "Employee Survey",
"status": "draft",
"created_at": "2026-01-20T14:00:00.000Z"
}
],
"meta": {
"page": 2,
"per_page": 25,
"total": 73,
"total_pages": 3
}
}
Meta 字段
| 字段 | 类型 | 描述 |
|---|---|---|
page | integer | 当前页码。 |
per_page | integer | 每页的项目数（实际应用的值）。 |
total | integer | 所有页面的总项目数。 |
total_pages | integer | 总页数（计算方式为 ceil(total / per_page)）。 |
遍历所有页面
当您需要从列表端点获取每个项目时，逐页遍历直到 page 超过 total_pages。
JavaScript
javascript
async function fetchAllForms() {
const allForms = [];
let page = 1;
let totalPages = 1;
do {
const response = await fetch(
`https://app.nueform.com/api/v1/forms?page=${page}&per_page=100`,
{
headers: {
"Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
},
}
);
const { data, meta } = await response.json();
allForms.push(...data);
totalPages = meta.total_pages;
page++;
} while (page <= totalPages);
console.log(`Fetched ${allForms.length} forms in total.`);
return allForms;
}
Python
python
import os
import requests
API_KEY = os.environ["NUEFORM_API_KEY"]
BASE_URL = "https://app.nueform.com/api/v1"
def fetch_all_forms():
all_forms = []
page = 1
total_pages = 1
while page <= total_pages:
response = requests.get(
f"{BASE_URL}/forms",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"page": page, "per_page": 100},
)
body = response.json()
all_forms.extend(body["data"])
total_pages = body["meta"]["total_pages"]
page += 1
print(f"Fetched {len(all_forms)} forms in total.")
return all_forms
异步生成器（JavaScript）
对于大型数据集，使用异步生成器在项目到达时逐个处理，而不是将所有内容加载到内存中：
javascript
async function* paginatedForms(perPage = 100) {
let page = 1;
let totalPages = 1;
do {
const response = await fetch(
`https://app.nueform.com/api/v1/forms?page=${page}&per_page=${perPage}`,
{
headers: {
"Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
},
}
);
const { data, meta } = await response.json();
totalPages = meta.total_pages;
for (const form of data) {
yield form;
}
page++;
} while (page <= totalPages);
}
// 使用示例
for await (const form of paginatedForms()) {
console.log(`Processing: ${form.title}`);
}
边界情况
空结果
如果没有匹配查询的项目，API 返回空的 data 数组，total 为 0：
json
{
"data": [],
"meta": {
"page": 1,
"per_page": 20,
"total": 0,
"total_pages": 0
}
}
超出总页数
请求超出 total_pages 的页码会返回空的 data 数组。meta 值仍然反映整体集合：
json
{
"data": [],
"meta": {
"page": 10,
"per_page": 20,
"total": 73,
"total_pages": 4
}
}
无效参数
无效的分页参数会被优雅处理：
| 输入 | 行为 |
|---|---|
page=0 或 page=-1 | 默认为 1 |
page=abc | 默认为 1 |
per_page=0 或 per_page=-5 | 默认为 1 |
per_page=500 | 限制为 100 |
per_page=abc | 默认为 20 |
最佳实践
批量获取时使用最大 per_page
获取所有资源时，设置 per_page=100 以减少 API 调用次数。每次调用都计入您的速率限制。
迭代前检查 total_pages
始终从 meta 对象读取 total_pages 来确定何时停止。不要无限迭代或假设固定的页数。
大数据集在页面间添加延迟
如果您要获取许多页面，在请求之间添加一个小延迟以避免触发速率限制：
javascript
// 在页面请求之间添加 200 毫秒延迟
await new Promise((resolve) => setTimeout(resolve, 200));
适时缓存总数
如果您只需要总数（例如显示"47 个表单"），请求 per_page=1 并读取 meta.total 以最小化数据传输：
curl
curl -X GET "https://app.nueform.com/api/v1/forms?per_page=1" \
-H "Authorization: Bearer nf_your_api_key_here"
分页结果反映的是每次请求时的数据状态。如果在页面请求之间创建或删除了项目，您可能会看到重复项或遗漏项。为了获得一致的快照，请快速获取所有页面或使用 Webhook 获取实时更新。