此文已由作者郑华斌授权网易云社区发布。
REST这词我们常常挂在嘴边,比如“开发一个rest接口”,又比如Spring项目的代码:
@RestControllerpublic class CommonController { @RequestMapping("/") public String index() { return "Welcome to Yanxuan DMS!";
}
CommonController使用了@RestController注解,顾名思义,告诉读者这是一个Rest接口的实现。然而以@RestController注解的接口却不一定符合Rest原则。结合最近的项目,总结下常见的违背Rest设计的一些做法。
一、一律使用POST或者GET方法
典型的错误做法:无论什么请求,一律用POST,或者‘增删改’用POST,‘查’用GET。
其实REST有个原则叫统一接口(uniform interface),统一接口原则建议了各http方法的使用场合,
GET:获取资源,返回消息头和消息表示,即header和body。
HEAD:获取资源元数据,返回消息头
DELETE:删除资源
POST:REST设计中,POST通常用来为一个已有资源创建一个从属资源(subordinate resource),如AWS S3的POST Object(或者称web post)接口。
PUT:创建或修改一个资源
PUT和POST的区别比较微妙,这里拿AWS S3(或者参考网易对象存储NOS)的接口设计来举例。其中AWS S3的详细API文档参见:http://docs.aws.amazon.com/Am...。 S3有两种资源,桶(bucket)和对象(object),对象从属于某个桶。
创建一个桶的接口为:
PUT /BucketName HTTP/1.1
Host: s3.amazonaws.com
创建/修改一个对象的PUT Object接口为:
PUT /BucketName/ObjectName HTTP/1.1
Host: s3.amazonaws.com[对象数据]
AWS S3同时提供了POST Object接口,同样可以创建/修改一个对象,如下
POST /BucketName HTTP/1.1Host: s3.amazonaws.comContent-Type: multipart/form-data; boundary=9431149156168[包含对象数据的body]
获取对象的GET Object接口为:
GET /BucketName/ObjectName HTTP/1.1
Host: s3.amazonaws.com
同样的创建/修改一个对象,一个用PUT方法,另一个用POST方法,为什么?关键在于URL,PUT请求的目标URL(这里为/BucketName/ObjectName),就是将来用于获取该对象的URL,即PUT Object和GET Object的URL是一致的。但是POST Object的URL与GET ObjectURL不一样,POST 请求只知道父资源的URL(即/BucketName),表示在该父资源下创建新资源,至于新资源的确切URL,是由服务器决定的,一般来说是POST请求的响应应该包含一个Location消息头,其包含新建从属资源的URL。
安全性safe和幂等性idempotent
REST设计还应该遵循安全性和幂等性约束,如下:
GET和HEAD应当是安全的:GET和HEAD请求不应该导致服务器状态发生改变
GET、HEAD、PUT和DELETE应当是幂等的:向一个URL发送多次PUT和DELETE请求,跟只做过一次请求一样。比如PUT不能是append语义,否则不幂等。GET和HEAD也是幂等。
统一接口原则的好处:
给一个资源URI,不用看文档就知道可以有GET、DELETE等操作及其意义,世界通用。
安全性和幂等性增加了http的可靠性:如果请求没成功(但也许已成功了),只需重新发一次即可,不用担心副作用。
二、HTTP Code一律返回200
典型的错误做法:无论成功失败,HTTP Code一律返回200,具体错误信息交由json body里的内容来判断,举例如下,
某甲服务xxx接口的响应如下
HTTP/1.1 200 OK{ "status":1, //1: 成功 0: 参数异常 -1: 失败
"message":"" //返回的消息
成功时返回的数据
}
某乙服务xxx接口的响应如下
HTTP/1.1 200 OK{ "code":200, //1: 成功 0: 参数异常 -1: 失败
"msg":"" //code非200时返回的错误信息
"data":{成功时返回的数据内容}
}
其实RESTful的设计的一个标志特征是充分并正确利用HTTP响应码,典型的如:
200 -- OK,成功
301 -- Moved Permanently,重定向
400 -- Bad Request,错误的请求,比如缺少参数或者参数值不对
403 -- Forbidden,无权限访问
404 -- Not Found,url不存在
500 -- Internal Server Error,系统错误,如数据库访问失败或者bug导致的错误
设计REST接口应该遵循上面的响应码,语义明确并通用。如果像上面例子那样,任何情况都一律返回200,而具体成功与否需要到http响应消息体里去解析,而且不同的服务或开发者自定义消息体的格式,那么服务调用方就需要针对不同的服务写不同的判断逻辑,增加系统交互复杂性。
有些通用的客户端,会针对301自动处理重定向,针对500以上的响应自动重试,而一律返回200的设计是没法使用这些特性的,只能调用方一一自个处理。
三、 面向操作而不是面向资源的url设计
典型的错误做法:设计的URI是面向操作而不是面向资源的,举例如下,
某系统 设计的渠道相关的URI是这样的:
新增渠道
POST /xhr/thirdparty/admin/channel/add.json?{渠道信息参数}
编辑渠道
POST /xhr/thirdparty/admin/channel/update.json?{渠道信息参数}
删除渠道
POST /xhr/thirdparty/admin/channel/delete.json?channelId=id
这里的接口设计有三个特点:
http方法都是POST;
URI里携带操作信息,如URI里出现“add”,“update”,“delete”等字眼;
同一个资源由于操作不一样而URI不一样。
其实REST式的设计中,URI即是资源的名称,也是资源的地址,因为不同的操作而资源地址不一样是不合适的。资源的操作(方法信息)应该由统一接口来表示,即http 方法PUT、POST、GET、DELETE等,而不应该放到URI中。
对照统一接口和面向资源这两个特征来设计,上面的接口RESTful化可以是这样的:
新增渠道
POST /xhr/thirdparty/admin/channel
[渠道具体信息]
修改渠道
PUT /xhr/thirdparty/admin/channel?channelId=id 或者PUT /xhr/thirdparty/admin/channel/${id}
[渠道具体信息]
删除渠道
DELETE /xhr/thirdparty/admin/channel?channelId=id或者DELETE /xhr/thirdparty/admin/channel/${id}
渠道的地址为/xhr/thirdparty/admin/channel?channelId=id或者/xhr/thirdparty/admin/channel/${id},重在url唯一。
参考文献
《RESTful Web Services》
文章来源: 网易云社区
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。