2019.11.26

pingan8787 · pingan8787 · commit b35ed52ecad0 · 2019-11-26T22:06:57.000+08:00
diff --git a/Cute-FullStack/【全栈修炼】RESTful架构及实践修炼宝典.md b/Cute-FullStack/【全栈修炼】RESTful架构及实践修炼宝典.md
@@ -55,46 +55,46 @@ REST 基本架构的四个方法：
 
 REST 定义了资源的通用访问格式，接下来一个消费者为实例，介绍 RESTful API 定义：
 
-1. 获取所有 user 
+1. 获取所有 users 
 
 ```
-GET /api/user
+GET /api/users
 ```
 
-2. 获取指定 id 的 user
+2. 获取指定 id 的 users
 
 ```
-GET /api/user/100
+GET /api/users/100
 ```
 
-3. 新建一条 user 记录
+3. 新建一条 users 记录
 
 ```
-POST /api/user
+POST /api/users
 ```
 
-4. 更新一条 user 记录
+4. 更新一条 users 记录
 
 ```
-PUT /api/user/100
+PUT /api/users/100
 ```
 
-5. 删除一条 user 记录
+5. 删除一条 users 记录
 
 ```
-DELETE /api/user/100
+DELETE /api/users/100
 ```
 
-6. 获取一个 user 的所有消费账单
+6. 获取一个 users 的所有消费账单
 
 ```
-GET  /api/user/100/bill
+GET  /api/users/100/bill
 ```
 
 7. 获取一个 user 指定时间的消费账单
 
 ```
-GET  /api/user/100/bill?from=201910&to=201911
+GET  /api/users/100/bill?from=201910&to=201911
 ```
 
 以上其中 RESTful 风格 API 几乎包含常见业务情况。
@@ -132,7 +132,7 @@ GET  /api/user/100/bill?from=201910&to=201911
 
 ### 2. 获取用户列表
 
-这一步我们会创建 RESTful API 中的 **user**，使用 GET 来**读取用户的信息列表**：
+这一步我们会创建 RESTful API 中的 **/users**，使用 GET 来**读取用户的信息列表**：
 
 ```js
 // index.js
@@ -141,7 +141,7 @@ const app = express();
 const fs = require("fs");
 
 // 定义 读取用户的信息列表 的接口
-app.get('/user', (req, res) => {
+app.get('/users', (req, res) => {
    fs.readFile( __dirname + "/" + "users.json", 'utf8', (err, data) => {
        console.log( data );
        res.end( data );
@@ -156,7 +156,7 @@ const server = app.listen(8081, function () {
 
 ### 3. 添加用户
 
-这一步我们会创建 RESTful API 中的 **user**，使用 POST 来**添加用户记录**：
+这一步我们会创建 RESTful API 中的 **/users**，使用 POST 来**添加用户记录**：
 
 ```js
 // index.js
@@ -173,7 +173,7 @@ const user = {
 }
 
 // 定义 添加用户记录 的接口
-app.post('/user', (req, res) => {
+app.post('/users', (req, res) => {
    // 读取已存在的数据
    fs.readFile( __dirname + "/" + "users.json", 'utf8', (err, data) => {
        data = JSON.parse( data );
@@ -186,14 +186,14 @@ app.post('/user', (req, res) => {
 
 ### 4. 获取用户详情
 
-这一步我们在 RESTful API 中的 URI 后面加上 **:id**，使用 GET 来**获取指定用户详情**：
+这一步我们在 RESTful API 中的 URI 后面加上 **/users/:id**，使用 GET 来**获取指定用户详情**：
 
 ```js
 // index.js
 // 省略之前文件 只展示需要实现的接口
 
 // 定义 获取指定用户详情 的接口
-app.get('/:id', (req, res) => {
+app.get('/users/:id', (req, res) => {
    // 首先我们读取已存在的用户
    fs.readFile( __dirname + "/" + "users.json", 'utf8', (err, data) => {
        data = JSON.parse( data );
@@ -206,7 +206,7 @@ app.get('/:id', (req, res) => {
 
 ### 5. 删除指定用户
 
-这一步我们会创建 RESTful API 中的 **user**，使用 DELETE 来**删除指定用户**：
+这一步我们会创建 RESTful API 中的 **/users**，使用 DELETE 来**删除指定用户**：
 
 ```js
 // index.js
@@ -215,7 +215,7 @@ app.get('/:id', (req, res) => {
 // mock 一条要删除的用户id
 const id = 2;
 
-app.delete('/user', (req, res) => {
+app.delete('/users', (req, res) => {
    fs.readFile( __dirname + "/" + "users.json", 'utf8', (err, data) => {
        data = JSON.parse( data );
        delete data["user" + id];
@@ -225,12 +225,114 @@ app.delete('/user', (req, res) => {
 })
 ```
 
+## 四、REST 最佳实践
+
+### 1. URL 设计
+
+#### 1.1 "动词 + 宾语"的操作指令结构
+
+客户端发出的数据操作指令都是"**动词 + 宾语**"的结构。
+
+如上面提到的，`GET /user` 这个命令，`GET` 是动词，`/user` 是宾语。根据 HTTP 规范，动词一律大写。
+
+动词通常有以下五种 HTTP 方法：
+
+GET：读取（Read）
+POST：新建（Create）
+PUT：更新（Update）
+PATCH：更新（Update），通常是部分更新
+DELETE：删除（Delete）
+
+#### 1.2 宾语必须是名词
+宾语就是 API 的 URL，是 HTTP 动词作用的对象。它应该是名词，不能是动词。
+
+比如，`/users` 是正确的，因为 URL 是名词，而下面就都是错误的了：
+```
+/getUsers
+/createUsers
+/deleteUsers
+```
+
+#### 1.3 建议复数 URL
+
+因为 URL 是名词，没有单复数的限制，但是还是建议如果是一个集合，就使用复数形式。如 `GET /users` 来读取所有用户列表。
+
+#### 1.4 避免多级 URL 
+
+避免在多层级资源时，使用多级 URL。常见案例如**获取某位用户的购买过的某一类商品**:
+
+```
+GET /users/100/product/120
+```
+
+这种 URL 语意不明，也不利拓展，建议只有第一级，其他级别用查询字符串来表达：
+
+```
+GET /users/100?product=120
+```
+
+### 2. 准确的状态码表示
+
+HTTP 五大类状态码有100多种，每一种状态码都有标准的（或者约定的）解释，客户端只需查看状态码，就可以判断出发生了什么情况，所以服务器应该返回尽可能精确的状态码。
+
+这边列举几个经常使用的状态码介绍：
+
+* **303 See Other**：表示参考另一个 URL。
+
+* **400 Bad Request**：服务器不理解客户端的请求，未做任何处理。
+
+* **401 Unauthorized**：用户未提供身份验证凭据，或者没有通过身份验证。
+
+* **403 Forbidden**：用户通过了身份验证，但是不具有访问资源所需的权限。
+
+* **404 Not Found**：所请求的资源不存在，或不可用。
+
+* **405 Method Not Allowed**：用户已经通过身份验证，但是所用的 HTTP 方法不在他的权限之内。
+
+* **410 Gone**：所请求的资源已从这个地址转移，不再可用。
+
+* **415 Unsupported Media Type**：客户端要求的返回格式不支持。比如，API 只能返回 JSON 格式，但是客户端要求返回 XML 格式。
+
+* **422 Unprocessable Entity**：客户端上传的附件无法处理，导致请求失败。
+
+* **429 Too Many Requests**：客户端的请求次数超过限额。
+
+* **500 Internal Server Error**：客户端请求有效，服务器处理时发生了意外。
+
+* **503 Service Unavailable**：服务器无法处理请求，一般用于网站维护状态。
+
+### 3. 服务端响应
+
+#### 3.1 应该返回 JSON 对象
   
+API 返回的数据格式应该是 JSON 一个对象。
+
+#### 3.2 发生错误时，不要返回 200 状态码
+
+在发生错误时，如果还返回 200 状态码，前端需要解析返回数据才知道错误信息，这样实际上取消了状态码，是不恰当的。
+
+正确的做法应该是在错误时，返回对应错误状态码，并将错误信息返回：
+
+```
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{
+  "error": "Invalid payoad.",
+  "detail": {
+     "surname": "This field is required."
+  }
+}
+```
+
+
+
 ## 参考资料
 
 1. [《维基百科 - 表现层状态转换》](https://zh.wikipedia.org/wiki/%E8%A1%A8%E7%8E%B0%E5%B1%82%E7%8A%B6%E6%80%81%E8%BD%AC%E6%8D%A2)
 2. [《RESTful风格的springMVC》](https://blog.csdn.net/wy5612087/article/details/52149249)
 3. [《Node.js RESTful API》](https://www.runoob.com/nodejs/nodejs-restful-api.html)
+4. [《RESTful API 最佳实践》](www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html)
 
 ## 关于我
 
