API设计：筛选，排序和翻页

知道了喵

已于 2023-05-06 20:02:56 修改

阅读量164

点赞数

分类专栏： Web APIs 文章标签： javascript 设计规范

于 2023-05-06 12:12:55 首次发布

本文链接：https://blog.csdn.net/qq_35129075/article/details/130524292

版权

Web APIs 专栏收录该内容

2 篇文章 0 订阅

订阅专栏

开门见山，直接说结论。学习过程见本文最后的参考

筛选设计最佳实践

语法一：只有一个筛选项的情况（不常用）

{
  "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
  }
}