6-2Restful

6.2 Restful

HTTP设计

• 通过URL进行资源定位，如获取id=8的用户则向/user/8发送请求
• 具有不同的请求方法（也叫请求谓词），主要有get、post、put、delete，获取资源使用get，新增资源使用post，整体更新使用put，删除资源使用delete
• 请求谓词中，除了post之外都是幂等的，幂等指的是对于一个接口采用同样的参数请求一次和多次结果一致，不会产生副作用。比如点击评论发布，评论被插入数据库，但是因为网络问题用户没有看到发布成功的消息，则多次点击发布按钮，幂等同样会只插入一次。
• get请求的相应是可以被缓存的
• 服务端要通过状态码来反映资源获取的结果，如404

Restful介绍

在web API开发中，有两种风格：面向过程（RPC）和面向REST

RPC

通过“控制器/操作方法”的形式来调用服务端的方法，也就是把服务端的代码当做了方法调用。这种风格的接口可能会用POST处理所有的操作方法（无论是新增、获取、还是删除）。在这样的接口中，通过QueryString或者请求报文来为服务器传递数据，只要是服务端能够正常完成客户端的请求，服务端统一返回200的http状态码，对于逻辑上的错误，同样返回200，只不过会在响应报文中不同的错误码来表示。

示例：

其中，更新、新增用户等操作要将用户信息以JSON格式放到请求报文中

由此可见，RPC的URL中包含以名词形式描述的资源（Person）和以动词形式描述的动作（GetAll）

Restful

每个控制器都是对一类资源的操作的集合，每个操作方法都被不同的HTTP谓词触发

[Route("api/[controller]")]
public class PersonsController : ControllerBase
{
    [HttpGet]
    public IEnumerable<Person> GetPersons();
    [HttpGet("{id}")]
    public Person GetPersons(long id); 
    [HttpPut("{id}")]
    public void UpdatePerson(long id,Person person);
    [HttpPost]
    public void SavePerson(Person person);
    [HttpDelete("{id}")]
    public void DeletePerson(long id);
}

其中新增用户信息以JSON格式放在请求报文中，在Restful风格中，URL中的单词都是名词，动作通过HTTP谓词来表述

Restful优缺点

优点：

• 所有资源尽量通过URL表示，避免通过QueryString、报文体对资源进行定位，URL语义性更清晰
• 增删改查都会对应相应的HTTP谓词
• get、put、delete等幂等操作可以对失败的请求自动重试
• 网管可以对get请求进行缓存
• 可以通过http状态码反映服务器端的处理结果，能够统一错误码
• 网关等系统可以根据状态码来分析系统的访问数据，比如通过http状态码分析有多少成功请求有多少失败请求

缺点：

• 真实系统资源复杂，很难清晰的进行资源划分
• 并不是所有的操作都能简单对应到put、get、delete、post
• 系统的改变，比如一开始设计为幂等，但后来更改了规则
• 通过URL不太符合中文的习惯，比如查询年级编号为8且年龄等于18的用户:person/class/8/age/18
• 某些客户端不支持put，delete请求

Restful如何传递参数

给服务器传递参数的3中形式：URL、QueryString、请求报文体，只有put、post支持请求报文体

Web Api参数传递建议：

• 对于保存、更新类的请求一般是用post，put请求，将全部参数放到请求报文体中
• 对于delete请求，要传递的参数一般是一个Id，所以使用QueryString即可
• 对于get请求，参数不会太长一般使用QueryString即可