笔记——asp.net core 中的 REST

REST（reprentational state transfer，表层状态转移）

REST原则：提倡按照HTTP的语义使用HTTP。

如果一个系统符合REST原则，我们就说这个系统是Restful风格的。

        在RPC风格的Web API系统中，我们把服务端的代码当成方法去调用而不用关心HTTP谓词的语义。

        即URL中，包含以名词形式描述的资源和一动词形式描述的动作，如：/Person/GetAll、/Person/GetById?id=5、/Person/AddNew、/Person/Update。

        在REST风格的Web API系统中，每个Controller都是对一类资源的操作的集合，每个操作方法都被不同的HTTP谓词出发。

        即URL在的单词都是名词，动作通过HTTP谓词来表述。 

补充：

1、Web API开发有两者风格：

• 面向过程的（简称RPC，是业务驱动的产物，更加自然）；
• 面向REST的（简称REST，要求开发人员对REST原则更了解，熟悉业务知识，并且有更高的设计能力）

2、HTTP的设计哲学包括：

（1）在HTTP中，我们通过URL进行资源的定位；

（2）在HTTP中，不同的请求方法（又被称为请求谓词）有不同的含义。

        主要的谓词有：GET、POST、PUT、DELETE、PATCH、OPTIONS等 

         不同谓词有不同的用途：
        获取资源用 GET、新增资源用 POST、整体更新（如果不存在则创建）资源用 PUT、删除资源用 DELETE。我们不应该错误地使用谓词，比如删除一个资源的时候，我们不能使用 GET 请求，而应该使用 DELETE 请求。

（3）在HTTP中，DELETE、PUT、GET请求应该是幂等的，而POST则不是幂等的。

幂等：对于一个接口采用同样的参数请求一次和请求多测的结果是一致的，不会因为多次氢气而产生副作用。

（4）在HTTP中，GET请求的响应是可用被缓存的，而DELETE、PUT、POST请求的响应是不可以被缓存的。客户端、网关等可以根据情况对 GET 请求的响应进行缓存，从而提升性能。

（5）在HTTP中，服务端要通过状态码来反映资源获取的结果。

3、服务端传递参数的三种方式：

（1）URL，更符合Restful规范，但不适合传递内容太长或传递参数太多

（2）QueryString，比较灵活但不适合传递太长的内容

  (3)请求报文体，不限制参数内容长度，且可通过JSON产地复杂的格式，但只有POST、PUT支持请求报文体，不支持或忽略GET、DELETE中的报文体。

4、在REST中，传递参数的三种方式的意义不同

（1）URL传递的参数主要用于对资源进行定位

（2）QueryString用来传递额外的数据，比如分页的页码等信息

（3）请求报文体应该用来供PUT和POST提交主要数据，报文体数据以JSON字符串形式进行传递。

        因为开发人员与设计人员对REST的理解程度不同，如果要求系统严格要求执行Restful风格，会导致传递方式混乱。因此建议为项目张参数传递方式指定一个强制性、容易理解、容易实施的标准。

        所以通常我们都是：

        对于保存、更新类的请求一般都是使用 POST、PUT 请求，把全部参数都放到请求报文体中；

        对于 DELETE 请求，要传递的参数就是一个资源的 ID，因此把参数放到 QueryString 中即可；

        对于 GET 请求，一般参数的内容都不会太长，因此统一通过 QueryString 传递参数就可以；当然对于极少数参数内容超过 URL限制的请求，由于 GET、PUT 请求都是幂等的，因此把请求改成通过 PUT 请求，然后通过报文体来传递参数。

5、微软为Web API提供的模板代码、示例代码大部分都严格遵守Restful风格。如果把它们改造为RPC风格，需要做如下操作：

（1）控制器上添加的[Route("[controller]")]修改为[Route("[controller]/[action]")]，这样就会匹配控制器的名字，而[action]就会匹配操作方法的名字。

（2）通过不同的路由配置，Asp.NET Core中的控制器可以支持多个同名的重载操作方法，但是匹配不当会导致开发人员认为一个URL请求应该调用A1方法，但是却调用了A2方法。因此，我们强制要求控制器中不同的操作用不同发方法名。

（3）把[HttpGet]、[HttpPost]、[HttpDelete]、[HttpPut]这些 Attribute 添加到对应的操作方法上。这不仅会帮助接口开发人员明确操作方法接收的请求类型，更能帮助 Swagger+OpenAPI
生成文档。
        注意：
        在 ASP.NET Core Web API中，如果控制器中存在一个没有添加[HttpGet]、[HttpPost]等的 public 方法，Swagger 就会报错“Failed to load API definition.”  

        对于这样的方法，请把[ApiExplorerSettings(IgnorApi=true)]添加到方法上，从而告知Swagger忽略这个方法。