RESTful 介绍
什么是RESTful?
一种软件架构风格、设计风格,而不是标准,只是提供了一组设计原则和约束条件。它主要用于客户端和服务端交互类的软件。基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制。
URL规范
1 不要大写
2 用-而不要用_
3 参数列表要encode (参见 对URL encode 解释 :https://www.cnblogs.com/kxm87/p/9276773.html)
4 每个网址代表一种资源,所以网址中不能有动词,只能有名词(特殊情况可以使用动词),而且所用的名词往往与数据库表名对应
5 URI中的名字表示资源集合,使用复数形式
控制版本号
将API的版本号放到URL中
比如:
https://api.example.com/v1/zoos
v{n} n代表版本号,分为整形和浮点型
整形的版本号: 大功能版本发布形式;具有当前版本状态下的所有API接口 ,例如:v1,v2
浮点型:为小版本号,只具备补充api的功能,其他api都默认调用对应大版本号的api 例如:v1.1 v2.2
HTTP请求方式
对于资源的具体操作类型由HTTP动词表示
常用的HTTP动词有下面四个(括号里是对应的SQL命令):
GET(SELECT):从服务器取出资源(一项或多项)
POST(CREATE):在服务器新建一个资源
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)
PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性,不如上架下架停用等某个字段状态)
DELETE(DELETE):从服务器删除资源
举例:
GET /product:列出所有商品
GET /product/ID:获取某个指定商品的信息
GET /product/ID/purchase :列出某个指定商品的所有投资者
GET /product/ID/purchase/ID:获取某个指定商品的指定投资者信息
POST /product:新建一个商品
PUT /product/ID:更新某个指定商品的信息
DELETE /product/ID:删除某个商品
安全性和幂等性
安全性:不会改变资源状态,可以理解为只读的
幂等性:执行1次和执行N次,对资源状态改变的效果是等价的
安全性和幂等性均不保证反复请求能拿到相同的response。以 DELETE为例,第一次DELETE返回200表示删除成功,第二次返回404提示资源不存在,这是允许的。
过滤信息
?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置。
?page=2&per_page=100:指定第几页,以及每页的记录数。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
?animal_type_id=1:指定筛选条件
状态码
200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
204 NO CONTENT - [DELETE]:用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
错误处理
1 不要发生了错误但给2xx响应,客户端可能会缓存成功的http请求;
2 正确设置http状态码,不要自定义;
3 Response body提供
即:返回的信息中将error作为键名,出错信息作为键值即可
1)错误的代码(日志/问题追查);
2)错误的描述文本(展示给用户)
补充:Java服务器端一般用异常表示 RESTful API的错误。
API 可能抛出两类异常:业务异常和非业务异常。
业务异常: 由自己的业务代码抛出,表示一个用例的前置条件不满足、业务规则冲突等,比如参数校验不通过、权限校验失败。
非业务类异常: 表示不在预期内的问题,通常由类库、框架抛出,或由于自己的代码逻辑错误导致,比如数据库连接失败、空指针异常、除0错误等等。
业务类异常必须提供2种信息:
1 如果抛出该类异常,HTTP响应状态码应该设成什么
2 异常的文本描述
在Controller层使用统一的异常拦截器:
1设置 HTTP响应状态码:对业务类异常,用它指定的 HTTPcode;对非业务类异常,统一500;
2Response Body的错误码:异常类名
3Response Body的错误描述:对业务类异常,用它指定的错误文本;对非业务类异常,线上可以统一文案如“服务器端错误,请稍后再试”,开发或测试环境中用异常的 stacktrace,服务器端提供该行为的开关。
其他
1 API的身份认证应该使用OAuth2.0协议标准
2 服务器返回的数据格式,应该尽量使用JSON,避免使用XML
3 比较复杂的接口不能确定是使用POST还是PUT时,要看具体的业务层代码,看看接口产生的结果是否幂等,如果幂等用PUT,相反用POST
如:接口接收到一资源,资源存在更新,不存在插入新数据,这个接口就要用PUT
参考自:
https://www.cnblogs.com/gaoya666/p/9100678.html
https://blog.csdn.net/u010622769/article/details/54341363/
https://www.cnblogs.com/fu-yong/p/9052623.html
https://www.cnblogs.com/aini521521/p/7777328.html
https://www.imooc.com/article/17650
https://blog.csdn.net/chenxiaochan/article/details/73716617
http://www.ruanyifeng.com/blog/2014/05/restful_api.html
https://blog.csdn.net/xude1985/article/details/52268533