Web API 设计理念:Restful 约定大于一切

752 阅读2分钟

“对于一个成熟的前端切图仔来说,压倒他的往往不是 Vue、React 这些框架,而是一个非常不起眼的 Web API 设计理念。”

# Restful 入手

Restful 是一个成熟的 API 设计理念,它是 Representational State Transfer 的简写,翻译过来就是 “表现性状态转换”。

不过我更愿意称它为"资源约定法则"。

资源,就是网络中的数据,包括文本,图片,文件等。

约定法则,就是被大家所公认的写法。一旦你不按照这种写法,不好意思,你就不是 Restful API。

在 Restful 中,我们常用 URL 代表资源,因为这是前后台的桥梁,没有了 URL ,前后台就失去了通信的媒介。

1、在 URL 的约定中,名称必须使用名词,有单复数的区别。

如果是集合,名词就必须使用复数,而单个的则使用单数名词。

http://localhost:3000/users

上面是一个代表用户管理的集合,叫 users。

对应请求后的数据集如下:

[  {"name": "zhangsan","id": 1  },  {"name": "王五","id": 2  }]

**2、名称中不能用动词定义,**否则就不是 Restful API 规范。

http://localhost:3000/getusers     x

这就是一个错误的定义方式。

3、要避免层级过深的 URL,建议使用查询参数的形式。

http://localhost:3000/users/id/1   x

推荐使用:

http://localhost:3000/users?id=1

4、几个常用的形式。

http 中的动词:

  • GET ——从服务器获取资源

  • POST ——对服务器新建资源

  • PUT ——对服务器更新资源

  • DELETE ——从服务器删除资源

对资源信息的过滤常使用以下形式:

  • GET /users?id=1 ——返回具体某个资源

  • GET /users?_page=2 ——返回数据中的某一页

  • GET /users?_page=2&_limit=20 ——对返回的数据进行分页

  • GET /users?_order=votes&_order=asc ——对数据进行点赞排序,升序(asc)降序(desc)

  • GET /users?_start=1&_end=3 ——筛选出从第二个到第四个(索引从0开始,不包含后者)

# 小结

总而言之,技术本身是很灵活的,作为设计者我们更需要灵活运用。有了一套约定的 API 设计,即便后端的数据没有搞出来,我们只要按照这套约定,提前对项目进行搭建规划,不仅能得到数据,提前完成前端工作都是十分有可能的。