RESTful API 设计规范 归纳总结

版权声明：本文为博主原创文章，未经博主允许不得转载。 https://blog.csdn.net/yun123lhf/article/details/88421297

一、设计方式（动词）

[code]1、GET（Select）     获取资源                                   幂等，不应该有副作用
2、POST（Create）    创建资源                                   不满足幂等性，有副作用
3、PATCH（Update）   更新资源的部分属性（很少用，一般用POST代替）    不满足幂等性，有副作用
4、PUT（Update）     更新资源，客户端需要提供新建资源的所有属性       幂等，有副作用
5、DELETE（Delete）  删除资源                                   幂等，有副作用

 

二、客户端发出的数据操作指令一般都是"动词+宾语"的结构

        例如：

               /GET/salary/list    :  展示员工列表

               /POST/staff/user   :  新建员工

              宾语要为名词，可以都是名词复数形式，并且要避免多级URL

 

三、HTTP状态码

字段名：

code

SUCCESS ：

[code]200 OK [GET]                 服务器成功返回用户请求的数据，该操作是幂等的
201 Created [POST/PUT/PATCH] 用户新建或修改数据成功
202 Accepted [*]             表示一个请求已经进入后台排队，多用于异步任务
204 No Content [DELETE]      用户数据删除成功

FAILED ：       

[code]400 Bad Request [POST/PUT/PATCH] 用户发出的请求有错误，服务器不理解客户端的操作，服务器没有进行新建或修改数据的操作，该操作是幂等的
401 Unauthorize  [*]       表示用户没有权限（令牌、用户名、密码错误），未通过身份验证
403 Forbidden [*]          表示用户得到授权，但是访问是被禁止的
404 Not Found [*]          用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的
405 Method Not Allowed     用户已经通过身份验证，但是所用的 HTTP 方法不在他的权限之内
406 Not Acceptable [GET]   用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）
410 Gone [GET]             所请求的资源已从这个地址迁移，且不会再得到的
415 Unsupported Media Type 客户端要求的返回格式不支持
422 Unprocessable Entity [POST/PUT/PATCH] 客户端上传的附件无法处理，导致请求失败
429 Too Many Requests      客户端的请求次数超过限额
500 Internal Server Error  客户端请求有效，服务器处理时发生了意外，用户将无法判断发出的请求是否成功
503 Service Unavailable    服务器无法处理请求，一般用于网站维护状态

   错误信息

   message

 

四、返回信息示例

[code]{"code":200,"message":"用户查询成功","succ":true,"data":[]}

 

五、幂等的概念

HTTP幂等性

Methods can also have the property of “idempotence” in that (aside from error or expiration issues) the side-effects of N > 0 identical requests is the same as for a single request.

                                                         ——HTTP/1.1规范中幂等性的定义

        在编程中，一个幂等操作的特点是其任意多次执行所产生的影响均与一次执行的影响相同。而从HTTP给的定义中，可以知道HTTP方法的幂等性是指一次和多次请求某一个资源应该具有同样的副作用。

        例如：

        从账户扣钱的操作，应该是幂等的，产生的影响要确保是只扣了一次钱，而不会因为多次刷新页面或调用接口，而多次扣钱。

页面显示分页查询的结果应该是幂等的，多次调用接口显示的数据可能不同，但不会对数据本身产生影响。

 

六、接口设计的幂等性

1、每个请求有它的唯一标识，请求处理完成后，要有它的标识记录状态，每次接受请求时要判断之前是否处理过

2、幂等设计

      int create_ticket()

      bool idempotent_withdraw(ticket_id, account_id, amount)

      获取一个服务器端生成的唯一的处理号ticket_id，它将用于标识后续的操作

 

七、参考资料：

https://www.geek-share.com/detail/2633024360.html

https://baijiahao.baidu.com/s?id=1591221393853082871&wfr=spider&for=pc

https://www.geek-share.com/detail/2750347069.html