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,只不过会在响应报文中不同的错误码来表示。

示例:

需求

地址

HTTP谓词

获取所有用户

/Person/GetAll

GET

获取Id=8的用户

/Person/GetById?id=8

GET

更新Id=8的用户

/Person/Update

Post

新增用户

/Person/AddNew

Post

删除id=8的用户

/Person/DeleteById?id=8

Post

其中,更新、新增用户等操作要将用户信息以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);
}

需求

调用方法

地址

HTTP谓词

加载所有用户

添加了[HttpGet]的GetPersons方法

/api/Persons

Get

获取Id=8的用户

添加了[HttpGet(“{id}”)]的GetPersons方法

/api/Persons/8

Get

更新Id=8的用户

添加了 [HttpPut(“{id}”)]的UpdatePerson方法

/api/Persons/8

Put

新增用户

添加了 [HttpPost]的SavePerson方法

/api/Persons

Post

删除id=8的用户

添加了 [HttpDelete(“{id}”)]的DeletePerson方法

/api/Persons/8

Delete

其中新增用户信息以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即可