api 查询 参数是附加到 api 请求的 url 的键值对，用于向服务器发送附加信息。它们允许客户端（例如网络浏览器或应用程序）在向服务器发出请求时指定某些条件或传递数据。
查询参数添加到 url 末尾的问号 (?) 后面。每个参数都是一个键值对，键和值之间用等号 (=) 分隔。如果有多个查询参数，则用“&”分隔。
如何使用查询参数：
过滤数据：客户端可以使用查询参数来过滤他们想要的数据。例如， ?category=books 可能会告诉服务器仅返回“书籍”类别中的项目。
分页：查询参数通常用于 api 请求中的分页，允许客户端指定要获取哪一页结果以及每页有多少个项目。示例：?page=2&limit=10.
排序和顺序：查询参数可用于指定数据应如何排序。例如，?sort=price&order=asc 可以指示服务器返回按价格升序排列的项目。
传递搜索词：api 通常使用查询参数来允许客户端搜索数据。例如，?search=laptop 可用于查找与术语“laptop”匹配的所有产品。
查询参数非常灵活，可以通过多种方式使用，具体取决于 api 的设计方式。它们允许客户端和服务器之间进行动态交互，从而更容易请求定制数据。
- 基本查询参数处理 此 api 处理程序演示了如何提取和使用查询参数来返回个性化问候语。
// pages/api/greet.js
export default function handler(req, res) {
const { name } = req.query; // get the 'name' query parameter
const greeting = name ? `hello, ${name}!` : 'hello, stranger!';
res.status(200).json({ message: greeting });
}
用法示例：
/api/greet?name=john 将返回 { "message": "你好，约翰！" }
/api/greet 将返回 { "message": "你好，陌生人！" }
- 多个查询参数 在此示例中，api 处理程序提取多个查询参数以根据用户输入返回格式化响应。
// pages/api/user.js
export default function handler(req, res) {
const { name, age } = req.query; // get 'name' and 'age' query parameters
if (!name || !age) {
res.status(400).json({ error: 'name and age are required' });
return;
}
res.status(200).json({ message: `user ${name} is ${age} years old.` });
}
用法示例：
/api/user?name=jane&age=28 将返回 { "message": "用户 jane 28 岁。" }
/api/user?name=jane 将返回 { "error": "姓名和年龄为必填项" }
- 带有默认值的可选查询参数 此示例演示如何通过在参数丢失时提供默认值来处理可选查询参数。
// pages/api/score.js
export default function handler(req, res) {
const { player = 'anonymous', score = '0' } = req.query; // default values if missing
res.status(200).json({ message: `${player} scored ${score} points!` });
}
用法示例：
/api/score?player=alex&score=100 将返回 { "message": "alex 得分 100 分！" }
/api/score 将返回 { "message": "匿名者得分为 0 分！" }
- 处理查询参数中的数组 next.js 允许查询参数作为数组传递。此示例演示如何处理值数组。
// pages/api/tags.js
export default function handler(req, res) {
const { tags } = req.query; // get 'tags' query parameter (array)
if (!tags) {
res.status(400).json({ error: 'tags are required' });
return;
}
res.status(200).json({ message: `you have selected these tags: ${tags.join(', ')}` });
}
用法示例：
/api/tags?tags=javascript&tags=react 将返回 { "message": "您已选择这些标签：javascript、react" }
/api/tags 将返回 { "error": "tags are required" }
- 带查询参数的分页 该处理程序演示了如何使用页面和限制的查询参数来实现分页。
// pages/api/items.js
export default function handler(req, res) {
const { page = 1, limit = 10 } = req.query; // Default values for page and limit
const startIndex = (page - 1) * limit;
const endIndex = startIndex + Number(limit);
// Dummy data for demonstration
const items = Array.from({ length: 100 }, (_, i) => `Item ${i + 1}`);
const paginatedItems = items.slice(startIndex, endIndex);
res.status(200).json({
currentPage: page,
perPage: limit,
items: paginatedItems,
});
}
用法示例：
/api/items?page=2&limit=5 将返回接下来的 5 个项目，例如 { "items": ["item 6", "item 7", "item 8", "item 9", "item 10"] }
/api/items（默认值）将返回前 10 个项目，例如 { "items": ["item 1", "item 2", ..., "item 10"] }
这些示例演示了在 next.js api 路由中使用查询参数的灵活性，涵盖单个或多个参数、可选值、数组和分页等常见模式。
