开门见山,直接说结论。学习过程见本文最后的参考
筛选设计最佳实践
语法一:只有一个筛选项的情况(不常用)
{
"filtering": {
"operator": "<lt, le, eq, ne, ge, gt, in, contains>",
"field": "string",
"value": "any"
}
}
语法二:多个筛选项, 筛选项的关系约定为and
{
"filtering": [{
"operator": "<lt, le, eq, ne, ge, gt, in, contains>",
"field": "string",
"value": "any"
},{
"operator": "<lt, le, eq, ne, ge, gt, in, contains>",
"field": "string",
"value": "any"
}]
}
语法三:嵌套结构的复杂筛选
{
"filtering": {
"operator": "<and, or>",
"operands": [
{
"operator": "<lt, le, eq, ne, ge, gt, in, contains",
"field": "string",
"value": "any"
},
{
"operator": "<lt, le, eq, ne, ge, gt, in, contains",
"field": "string",
"value": "any"
},
{
"operator": "<and, or>",
"operands": [
{
"operator": "<lt, le, eq, ne, ge, gt, in, contains",
"field": "string",
"value": "any"
},
{
"operator": "<lt, le, eq, ne, ge, gt, in, contains",
"field": "string",
"value": "any"
},
{
"operator": "<and, or>",
"operands": []
},
]
},
]
}
}
排序设计最佳实践
请求参数:
"sort": [
{
"field": "string",
"direction": "<asc, desc>"
},
{
"field": "string",
"direction": "<asc, desc>"
}
]
扩展:
如果需要在浏览器中展示,可以这样设计/products?sort=popularity_desc,price_asc
翻页设计最佳实践
设计一:Offset Pagination
优点:实现简单
缺点:处理大数据有性能问题;增删数据时有数据一致性问题
应用:Spotify就是使用了这种设计方式。
请求参数:
"paging":{
"limit":100,
"page":1
}
响应数据:
"paging":{
"limit":100,
"page":1,
"total": 123, // rows
}
设计二:Cursor-based Pagination
应用:Twitter使用了这种设计
请求参数:
"paging":{
"limit":10,
"cursor":0
}
响应数据:
{
"data": [
{"id": 1, "name": "Alice"},
{"id": 2, "name": "Bob"},
{"id": 3, "name": "Charlie"},
...
{"id": 50, "name": "Zoe"}
],
"paging": {
"limit": 100,
"cursor": "eyJpZCI6MzQ2NTAsInNlcXVlbmNlIjozNTYyMH0=",
"total": 123, // rows
}
}
⚠️注意:
- 约定cursor=0为第一条数据。当响应数据的cursor=0时, 即翻到了最后一页。
- cursor 要脱敏
翻页设计小结
如果需要在浏览器的URL中显示,可以设计成https://xxx/page_size=10&page_number=1
或https://xxx/cursor=0