RESTful API风格
88530198 2019-11-05
任何对外提供服务的应用都绕不开API的发布，你的API可能是这个样子：
www.baidu.com/api/v1/getUsername?id=1 或者 www.baidu.com/app/index.php?r=info/user/getUsername&id=1
如果答案是YES，那么用句很潮的话，我们可以说你的API很不RESTful。
API风格
首先要说，不管你的API属于哪种风格，只要能够满足工作需要，就足够了。API格式并不存在绝对的标准，只存在不同的设计风格。
API设计包含两部分：请求和响应。
请求包含：请求URL、请求方法、请求头部信息等。
响应包含：响应体和响应头部信息。
一个请求URL的组成：
https://www.baidu.com:443/app/index.php?r=info/user/getUsername&id=1#tag # 请求方法：GET # 请求协议：protocal: https # 请求端口：port: 443 # 请求域名：host: www.baidu.com # 请求路径：pathname: /app/index.php # 查询字符串：search: r=info/user/getUsername&id=1 # 页面书签：hash: #tag
根据URL组成部分：请求方法、请求路径和查询字符串，我们有几种常见的API风格。比如当删除id=1的作者编写的类别为2的所有文章时：
# 纯请求路径 GET www.baidu.com/articles/delete/authors/1/categories/2 # 一级使用路径，二级以后使用查询字符串 GET www.baidu.com/articles/delete/author/1?category=2 # 纯查询字符串 GET www.baidu.com/deleteArticles?author=1&category=2 # RESTful风格 DELETE www.baidu.com/articles?author=1&category=2
前面三种都是GET请求，主要的区别在于多个查询条件时怎么传递查询字符串，有的通过使用解析路径，有的通过解析传参，有的两者混用。同时在描述API功能时，可以使用article/delete，也可以使用deleteArticles。
而第四种RESTful API最大的区别在于行为动词DELETE的位置，不在URL里，而在请求方法中。
RESTful设计风格
REST（Representational State Transfer 表现层状态转移）是一种软件架构风格、设计风格，而不是标准。主要用于客户端和服务端的API交互，它的优势在于更简洁、清晰、可读性强。
REST的主要特点是：
- 客户端和服务端是无状态的，任意请求都包含了处理需要的所有信息，同时服务端的变更对客户端是透明的。
- 资源用
URI（Universal Resource Identifier 通用资源标识）来表示，通过请求方法来指明操作类型：GET/POST/PUT/DELETE。
无状态是最重要的特性，大部分的Client-Server，Brower-Server也都能很好的支持。第2点则是我们需要去关注的。
REST URL
表现层状态转移（REST）是一个大的概念，也不好理解，我的理解就是在URL的定义上能够清楚的表示其请求含义。它的核心思路就是动词+宾语：
DELETE www.baidu.com/api/v1/articles?author=1&category=2 # 动词 DELETE，表示要进行的操作是删除，即状态转移 # 宾语 articles，表示文章这种资源URI，推荐用复数，即表现层 # 定语 author=1&category=2，表示具体是什么资源 # 版本 api/v1，这个能够帮助我们更好的进行版本的升级，同时不影响原有的请求
我们用articles来指明资源类型，用author=1&category=2来在确定具体的资源，用GET/POST/PUT/DELETE来指明要进行的增删改查操作。
这种风格相比于/api/deleteArticles，声明的方法数量只有1/4，各个接口之间的风格也更加统一，调用起来更加清晰。
同时这种方法能够保证浏览器常规能访问的到的GET请求对资源来说是安全的。比如别人给我们发送了一个链接：/deleteArticle?id=1，我们绝对不会希望随便点击一下就会跳转到浏览器访问，然后误删了这个资源。
响应状态码
除了请求URL有要求，在响应时也有一些要求。我们知道状态码有：
1xx:请求相关信息2xx:操作成功3xx:重定向4xx:客户端错误5xx:服务端错误
所有的状态码 共有100多种，涵盖了绝大多数常见的网络场景，而且是网络通用的定义规范和解释，因此我们应该尽可能使用精确的状态码。
当前有一些不太恰当的做法是即便请求出错，依然使用200状态码，转而将错误信息包含在响应体中，或者响应使用纯文本导致无法和正常数据一样标准化解析，如：
httpCode: 200
response: {
status: 1,
msg: '请求无权限'
}
# 或：
httpCode: 200
response: '请求无权限'但我们其实可以用更精确的状态码403代表权限不足，所以合适的响应结果应该是：
# 异常时
httpCode: 403,
httpErrorMsg: '请求无权限'
# 正常时：
httpCode: 200,
response: {
status: 0,
msg: '',
data: []
}总结
RESTful是一种API设计风格，并不是一种强制规范和标准，它的特点在于请求和响应都简洁清晰，可读性强。
我们主要关注几点：
- 无状态
- 请求
URL = 动作（GET/POST/PUT/DELETE）+ 资源 - 响应使用精确的状态码和
JSON格式数据
参考资料
- RESTful API 最佳实践: http://www.ruanyifeng.com/blo...
- RESTful: https://baike.baidu.com/item/...
- 怎样用通俗的语言解释REST，以及RESTful？: https://www.zhihu.com/questio...
- Status Code Definitions: https://www.w3.org/Protocols/...
