P6-3 Restful：想说爱你不容易

Restful：想说爱你不容易

什么是Restful

Web API两种风格：面向过程（RPC）、面向REST（REST）

RPC

RPC：“控制器/操作方法“的形式把服务器端的代码当成方法去调用。
- 把HTTP当成传输数据的通道，不关心HTTP谓词。
- 通过QueryString、请求报文体给服务器传递数据。状态码。
  - 比如：/Persons/GetAll、/Persons/GetById?id=8、/Persons/Update、/Persons/DeleteById/8；

REST

在REST风格的Web API中，接口把服务器端当成资源来处理。
REST风格的接口按照HTTP的语义来使用HTTP协议
- HTTP的语义。比如你有一辆小轿车，设计小轿车的本意是让你出行更简单。而你却用它去拉白菜~所以这就算是违背了语义
HTTP的设计哲学包含一下几个重点内容
- 1、URL用于资源的定位：/user/888、/user/888/orders；
- 2、HTTP谓词：GET、POST（新增）、PUT（整体更新）、DELETE、PATCH（局部更新）等；
- 3、什么是“幂等”，举例？DELETE、PUT、GET是幂等的，POST不幂等；
  - 幂等：对于一个接口采用同样的参数请求一次和请求多次的结果是一致的，不会因为多次请求而产生副作用
- 4、GET的响应可以被缓存，而DELETE、PUT、POST请求的响应式不可以被缓存的
- 5、服务器端要通过状态码来反映资源获取的结果。比如：404、403（没有权限）、201（新增成功）等

选择

RPC：业务驱动，自然。(业务驱动的产物)
REST：要求开发人员对REST原则更了解、并且有更高的设计能力。
两者风格没有好坏的区分

郭德纲的老师的一句话

Restful的优缺点

REST的优点

1、通过URL对资源定位，语义更清晰；
2、通过HTTP谓词表示不同的操作，接口自描述；
3、可以对GET、PUT、DELETE请求进行重试；
4、可以用GET请求做缓存；
5、通过HTTP状态码反映服务器端的处理结果，统一错误处理机制。
6、网关等可以分析请求处理结果。

REST的缺点

1、真实系统中的资源非常复杂，很难清晰地进行资源的划分，对技术人员的业务和技术水平要求高。
2、不是所有的操作都能简单地对应到确定的HTTP谓词中。
- 比如业务操作，请假、核销等
3、系统的进化可能会改变幂等性。
- 初代代码，经过不同开发人员，一层一层的改变，幂等性肯定就会被改变的
4、通过URL进行资源定位不符合中文用户的习惯。
5、HTTP状态码个数有限。
6、有些环节会篡改非200响应码的响应报文。
- 有一些运营商、路由器、浏览器会对响应报文来进行篡改
- 比如把404状态码的响应报文篡改成广告等
7、有的客户端不支持PUT、DELETE请求。
- 老路由器不支持或者小运营商不支持等

选择

1、REST是学术化的概念，仅供参考。
- 为什么AWS、ES等比较RESTful。
  - 因为像服务器等都式可以资源化的
- 为什么阿里、腾讯等很多系统不RESTful？
  - 而国产都是业务变动很大的，所以对吧~
2、根据公司情况，进行REST的选择和裁剪。
- 因此在进行项目开发的时候，需要根据项目特点、公司人员等多方面的情况，确定一个符合项目情况的定制版Restful规范

Restful中如何传递参数

HTTP传递参数的三种方式
- URL：适合定位；长度限制。
- QueryString：灵活；长度限制。
- 请求报文体：灵活；长度不限制；不支持GET、Delete。
三种方式的不同语义
- URL：资源定位。
- QueryString：URL之外的额外数据。
- 请求报文体：供PUT、POST提供数据。

实施指南

1、完全按照HTTP语义来写，要求太高。
- 国产基本能做到的很少~ OS:几乎没有
2、杨中科老师的对于Web API参数的传递建议如下：
- 1）对于保存、更新类的请求POST、PUT请求，把全部参数都放到请求报文体中；
- 2.对于DELETE请求，要传递的参数就是一个资源的id，因此把参数放到QueryString中即可；
- 3）对于GET请求，一般参数的内容都不会太长，因此统一通过QueryString传递参数就可以。对于极少数参数内容超过URL限制的请求，由于GET、PUT请求都是幂等的，因此我们把请求改成通过PUT请求，然后通过报文体来传递参数。

//1）对于保存、更新类的请求POST、PUT请求
/Users/5 PATCH
{"email":"[email protected]","age":5} //杨中科老师喜欢用这种

/Users/5 PATCH
{"id":"5";"email":"[email protected]","age":5}

//2.对于DELETE请求，要传递的参数就是一个资源的id，看个人选择
/Users/5 DELETE 

/Users?id=5 DELETE

返回错误码：200派与4xx派的“对决”

状态码

1、REST：通过HTTP状态码返回服务器端的处理结果。
2、问题：
- 1）HTTP状态码数量有限；
- 2）HTTP的状态码并不适合用来表示业务层面的错误码，它是一个用来表示技术层面信息的状态码。
  - 新增用户的操作中，如果服务器端要求Json格式，客户端提交XML，服务器返回400是没问题的。但是如果用户名格式错误或者用户名重复，存在200派和400派。
400派观点
- 1、网关等可以监控HTTP状态码，如果接口频繁出现4xx状态码，那么就说明客户端的代码不完善。
- 2、很多的系统都是按照HTTP状态码的不同含义进行设计的。如果失败了服务器端返回的状态码还是200的话，这会违背软件设计的初衷。
200派观点
- 网络的问题归网络、业务的问题归业务。业务错误不应该和技术错误混在一起。把系统日志和业务日志区分开。

大企业也不统一

百度：200派；
谷歌：400派；
同一家公司：
- 企业微信和微信小程序：200派；
- 微信支付：400派；

杨中科老师的观点：精简版的400派

1、对于数据库服务器连接失败、请求报文格式、服务器端异常等非业务错误，服务器端应该返回4xx、5xx等状态码。
2、对于业务层面的错误，比如用户不存在，我们要使用4xx等HTTP状态码返回。
- 同样在响应报文体中给出详细的错误信息，比如{“code”:3,”message”:”用户不存在”}。
3、不仅要返回4xx的HTTP状态码，而且不要忘了通过响应报文体给出详细的错误信息。
- 对于用户不存在，不仅要404，而且把响应报文体设置为{“code”:3,”message”:”用户名已存在”}，这样能区分出来是哪里的问题。

Restful实现指南

实现建议

1、使用RPC风格：Users/AddNew、Users/GetAll、Users/DeleteById。
2、对于可以缓存的操作，使用GET请求；
- 对于幂等的更新操作，使用PUT请求；
- 对于幂等的删除操作，使用DELETE请求；
- 对于其他操作，统一使用POST请求。
3、参数：保存、更新类的请求使用POST、PUT请求，把全部参数都放到请求报文体中；
- 对于GET和DELETE请求，把参数放到QueryString中。推荐尽量使用URL做资源定位。
4、对于业务错误，服务器端返回合适的4XX状态码，不知道该选择哪个状态码就用400；同时，在报文体中通过code参数提供业务错误码以及错误消息。
5、如果请求的处理执行成功，服务器端返回值为200的Http状态码，如果有需要返回给客户端的数据，则服务器端把这些数据放到响应报文体中。

实现技术

1、控制器上 [Route("[controller]/[action]")]
2、强制要求控制器中不同的操作用不同的方法名
3、把[HttpGet]、[HttpPost]、[HttpDelete]、[HttpPut]等添加到对应的操作方法上。
注意：如果控制器中存在一个没有添加[HttpGet]、[HttpPost]等的public方法，Swagger就会报错，可以用[ApiExplorerSettings(IgnoreApi = true)]