API设计:筛选,排序和翻页

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

筛选设计最佳实践

语法一:只有一个筛选项的情况(不常用)

{
  "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=1https://xxx/cursor=0

参考

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值