.Net Core 教程 Part4 – (11)(12)(13)(14)(15) Restful API

Part4-11 什么是REST

RPC

1、Web API两种风格:面向过程(RPC)、面向REST(REST)

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

REST

REST:按照HTTP的语义来使用HTTP协议

  • URL(Uniform Resource Locator)用于资源的定位:/user/888(获取888用户)、/user/888/orders(获取用户888的所有订单,而不是GetOrders?userid=888);
  • HTTP谓词:GET、POST(新增)、PUT(整体更新,更新所有字段)、DELETE、PATCH(局部更新,只更新几个属性)等;
  • 什么是“幂等”,举例?发生一次和发生多次是一样的。DELETE、PUT、GET是幂等的,POST不幂等;
    • List list; list.Add(3);//不是幂等的
    • Dictionary dict; dict[“a”]=”b”;//幂等的
    • i++;//不是幂等的
    • i=6;//是幂等的
  • GET的响应可以被缓存;
  • 服务器端要通过状态码来反映资源获取的结果:404、403(没有权限)、201(新增成功)。

RPC VS REST:

  • RPC:业务驱动,自然。
  • REST:要求开发人员对REST原则更了解、并且有更多的设计能力。

下面举个Rest例子:

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

Part4-12 REST的优点

1、通过URL对资源定位,语义更清晰;(Classes/5/Students VS GetStudents?classId=5)

2、通过HTTP谓词表示不同的操作,接口自描述

3、可以对GET、PUT、DELETE请求进行重试;(浏览器,网关中重试,缓存等)

4、可以用GET请求做缓存

5、通过HTTP状态码反映服务器端的处理结果,统一错误处理机制。

6、网关等可以分析请求处理结果。

Part4-13 REST的优点

1、真实系统中的资源非常复杂,很难清晰地进行资源的划分,对技术人员的业务和技术水平要求高。

2、不是所有的操作都能简单地对应到确定的HTTP谓词中。

3、系统的进化可能会改变幂等性。

4、通过URL进行资源定位不符合中文用户的习惯。

5、HTTP状态码个数有限。

6、有些环节会篡改非200响应码的响应报文。

7、有的客户端不支持PUT、DELETE请求。

选择

1、REST是学术化的概念,仅供参考。为什么AWS、ES等比较RESTful。为什么阿里、腾讯等很多系统不RESTful?

2、根据公司情况,进行REST的选择和裁剪。

Part4-14 RESTful传递参数

HTTP传递参数的三种方式

  • URL:适合定位长度限制
    • Schools/红星小学/Classes/3/No/2/5/6/Students
    • Students?SchoolName=红星小学&class=3&row=5
  • QueryString:灵活长度限制
  • 请求报文体:灵活长度不限制不支持GET、Delete

三种方式的不同语义

  • URL:资源定位。
  • QueryString:URL之外的额外数据。(URL中的随机数等)
  • 请求报文体:供PUT、POST提供数据。

实施指南

1、完全按照HTTP语义要求高。

2、一些供参考的建议:

1)对于保存、更新类的请求POST、PUT请求,把全部参数都放到请求报文体中;

  • /User/5 PATCH {“email”:”a@b.com”, “age”:5}
  • /User PATCH {“id”:5, email”:”a@b.com”, “age”:5}

2)对于DELETE请求,要传递的参数就是一个资源的id,因此把参数放到QueryString中即可;

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

Part4-14 ASP.NETCore如何返回错误码

状态码:

1、REST:通过HTTP状态码返回服务器端的处理结果。

2、问题:

1)HTTP状态码数量有限;

2)HTTP的状态码并不适合用来表示业务层面的错误码,它是一个用来表示技术层面信息的状态码。新增用户的操作中,如果服务器端要求Json格式,客户端提交XML,服务器返回400是没问题的。但是如果用户名格式错误或者用户名重复,存在200派和400派。返回200派 {“code”: 9} 或者 返回400派

400派

  • 网关等可以监控HTTP状态码,如果接口频繁出现4xx状态码,那么就说明客户端的代码不完善。
  • 很多的系统都是按照HTTP状态码的不同含义进行设计的。如果失败了服务器端返回的状态码还是200的话,这会违背软件设计的初衷。

200派

  • 网络的问题归网络、业务的问题归业务。业务错误不应该和技术错误混在一起。把系统日志和业务日志区分开。

大企业也不统一:

  • 百度:200派;
  • 谷歌:400派;
  • 同一家公司:
  • 企业微信和微信小程序:200派;
  • 微信支付:400派;

仅供参考的建议:

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

Part4-15 ASP.NET Core中Rest落地指南

实现建议

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]”)]

  • [controller]/[action] 优先根据action方法名称去匹配
  • [controller] 根据路径匹配

2、强制要求控制器中不同的操作用不同的方法名(虽然可以支持重载相同方法)

3、把[HttpGet]、[HttpPost]、[HttpDelete]、[HttpPut]等添加到对应的操作方法上。

注意:如果控制器中存在一个没有添加[HttpGet]、[HttpPost]等的public方法,Swagger就会报错,可以用[ApiExplorerSettings(IgnoreApi = true)]

.Net Core 教程 Part4 - (11)(12)(13)(14)(15) Restful API
存在public方法时会出错 需要改成privte
.Net Core 教程 Part4 - (11)(12)(13)(14)(15) Restful API
加上swagger不显示的标签 隐藏
.Net Core 教程 Part4 - (11)(12)(13)(14)(15) Restful API
实践

本文版权归Chaoqiang's Blog站点所有,发布者:chaoqiang,转转请注明出处:http://www.zhengchaoqiang.com/1352.html

(0)
打赏 微信扫一扫 微信扫一扫 支付宝扫一扫 支付宝扫一扫
上一篇 2021-12-18 09:20
下一篇 2021-12-18 12:22

相关推荐

发表回复

您的电子邮箱地址不会被公开。 必填项已用*标注

近期个人博客正在迁移中,原博客请移步此处,抱歉!