Web 技术研究所

我一直坚信着,Web 将会成为未来应用程序的主流

REST API 设计之 —— 通用查询参数

  在 MySQL 中,最常用的几个东西是 where、order by、limit,以及 select 后面的字段表。这个东西就能构成最基础的查询了。但是在大型项目中,查询语句的编写基本都是 DBA 的工作。程序直接拼凑出来的 SQL 语句肯定是会有性能问题的。这就直接影响到了接口设计。

我们无法自由地查询

  最理想的状态当然是前端直接提供 SQL,爱怎么查就怎么查。但这是不现实的,别说前段,就连 Web 的后端开发者可能都接触不到 SQL。数据库结构很复杂,不熟悉结构的开发者写出来的 SQL 语句总是会有性能问题的。比如将一个没索引的字段作为查询条件就会掉进坑里。所以 Web API 上的筛选和排序功能总是非常有限的。

  我最初设计 API 的时候没考虑到查询的局限性,把 API 设计得跟个 SQL 语句似得,把所有查询条件放入一个叫 where 的参数。比如这样 GET /list?where%5Bstatus%5D=1   于是就被大家吐槽到死了。确实如果查询条件非常有限的情况下,where 在这里毫无作用。后来整个设计就改为不带 where,直接参数上了。比如上面这个查询将以下面的形式传递。 GET /list?status=1   其实除了请求参数,排序字段也是同理。SQL 中一定是写死了固定的几套排序方式,所以 API 中也不需搞 order by 之类的东西,直接上参数。

可以通用的字段们

  一般查询是不会对 limit 做限制的,所以对 limit 的查询接口总是开放的。当然,MySQL 的 limit 有两个参数,有个 offset 存在。所以在 API 设计中直接将 offset 和 limit 作为两个参数,供所有列表类查询使用(当然为了安全,limit 参数可能需要一个上限)。
  SQL 语句中 select 后面的字段表也是可以作为通用参数的。即使数据库查询中不支持也没关系,后端程序取出前端所需的字段后再响应也是可以做到的。比如需要查询一组订单号,但调用订单查询的接口时,数据中的每一项都是一个完整的订单信息。这些数据中其实只有订单号才是我的需求,其它传输全部浪费了,所以加入一个 fields 参数可以选择所需的字段。

总结

  在 Web API 中,offset、limit、fields 这三个是最基本的通用查询参数。当然根据不同的环境也许会有更多,但我想这三个基本查询参数应该总是可以提供的。

网名:
34.203.245.*
电子邮箱:
仅用于接收通知
提交 悄悄的告诉你,Ctrl+Enter 可以提交哦
神奇海螺
[查看全部主题]
各类Web技术问题讨论区
发起新主题
本模块采用即时聊天邮件通知的模式
让钛合金F5成为历史吧!
次碳酸钴的技术博客,文章原创,转载请保留原文链接 ^_^