RestFul规范,看起来很美

RestFul 也不是什么新鲜的玩意,近几年开放平台火爆后大家认识了它,昨天把一套接口拿给人看,就被鄙视了,说接口不符合 Restful 规范,郁闷万分,确实没有深入的去看 Restful 规范,还以为是 Http 返回 json 或 xml 就叫Restful了,于是小看下具体规范。

由于restful规范规则太多,懒得写,所以就分点场景随便举几个例子。

方法规范

对于方法来说,资源的对应的操作应该使用请求方法标识。比如规范的方法如

//获取用户信息
GET /user/username HTTP/1.1
Content-Type: application/json; charset=utf-8

//新增一个用户
PUT /user HTTP/1.1
username=uname&password=pwd

//删除一个用户
DELETE /user/username HTTP/1.1

//修改一个用户
POST /user/username  HTTP/1.1


<!-- more -->

URI /user/user/username 仅为资源的地址,很多平台的设计如下:应该是不符规范的

//新增一个用户1  不符合规范
GET /user/add?uname=uname&pwd=pwd HTTP/1.1

//新增一个用户2 不符合规范
POST /user HTTP/1.1
act=add&uname=uname&pwd=pwd

//删除一个用户 不符合规范
GET /user/delete?uname=uname HTTP/1.1

结论: 利用 GET/POST/PUT/DELETE 做为动作描述

  1. GET:获取资源,一般都有last-modify头
  2. POST:复合操作,有时可以替代PUT和DELETE,比如一个动作操作多个资源时可以使用。
  3. PUT:创建资源,且URI非常明确时使用PUT,比如 /user 使用put方法则表示创建用户
  4. DELETE:删除资源,和PUT类似,URI明确时使用,否则应该使用POST

另外还有OPTIONS,TRACE方法,一般用的不多,OPTIONS方法可以规范化,暂时不多说使用场景。

错误码

按照规范,响应的错误码也是HTTP返回状态码的,也就是 2XX,3XX,4XX,5XX等,客户端根据响应头里面的状态码去在客户端适配

对于 Http 状态码就不说了,比如404资源找不到,500:服务器内部错误,对于找不到的错误码,应该算00,比如555错误码没有适配,就解释为500.

URL设计规范

URI应该层级分明,意义清晰,最好不带.jsp,.htm等文件后缀,其实这点对于大部分接口设计上来说来是很遵守的,发竟看上去规划的不错。与第一点:方法相结合后 /user/add 这样的设计就应该改为 /user 方法使用PUT。

小结:看上去很美

另外还有比较多的细节就不说了,比如请求头和响应应的规范,争议不大,总体来说个人还是认可的,思路清晰。

但是还是感觉:看上去很美,如果真拿以上规范当事的话,那么国内目前还没有一家厂商把接口设计的符合规范的。当然这不是因为没有前例,Restful是早期的概念,在开放平台还没来得及火爆之前,WEBDAV,SVN 等系统还是遵循着规范的。

Restful 规范的最大好处就是清晰,设计一套规范化的接口可以让人一看上去就能大概能理解。目前开放平台设计的大概一般就是一个链接地址,不管是 POST 还是 GET 或其它,状态码嘛当然是在响应体里面的一个字段表示的。看多了之后也不觉得有问题,也是挺清晰的,相比标准的规范来说,适应性,容错性,扩展性更高。

当然也有编码方面的原因,如果已经搭建了一个应用,在应用的基础上设计一套开放平台,那么就得和现有应用兼容,现在有很多方面与开发习惯不一样,随便一说都会有很多:

  1. 比如服务器定义了默认404,500错误码的页面,那么就无法兼容,需要废了服务器配置自己做。
  2. 喜欢用ajax的也要多写些方法监听非200响应码,喜欢用Jquery或其它框架的朋友能否正常错误处理。(貌似jQuery的fail方法还不能拿出消息体)
  3. 如果服务器禁用了一些“不安全”的方法,比如PUT/DELETE等,那么规范也是徒劳。
  4. 感觉Java就是为了restful而生的,servlet上有各种doGet,doPost方法甚至专门针对请求头里面lastModify值的getLastModified方法都有,但是常规的编程人员肯定这样写了doGet(args){ this.doPost(arghs) },或者使用各种Web框架,就辜负设计者对restful的一片好意

当然,准备搭建一个专门放 Restful 服务的应用,完全符合 Restful 规范也完全没问题。我们做的是产品,只要用户方便(清晰,一看就明白,用户是否有必要接收你的规范?)我们方便(如果同时又有 Web 服务,或是已经使用了需要的 Web 架构,是否真的要不顾兼容硬套规范?),所以只能说,规范是看上去挺美,真正是的需要严格遵守规范,那就看实际情况了~。