Asp.Net Core Rest风格

## 1.REST

1.1 RPC

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

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

1.2 REST

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

• URL用于资源的定位：/user/888、/user/888/orders
• HTTP谓词：GET、POST（新增）、PUT（整体更新）、DELETE、PATCH（局部更新）等
• “幂等”，DELETE、PUT、GET是幂等的，POST不幂等
• GET的响应可以被缓存
• 状态码：404、403（没有权限）、201（新增成功）

1.3 REST优缺点

优点：

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

缺点：

• 真实系统中的资源非常复杂，很难清晰地进行资源的划分，对技术人员的业务和技术水平要求高
• 不是所有的操作都能简单地对应到确定的HTTP谓词中。
• 系统的进化可能会改变幂等性
• 通过URL进行资源定位不符合中文用户的习惯
• HTTP状态码个数有限
• 有些环节会篡改非200响应码的响应报文
• 有的客户端不支持PUT、DELETE请求

REST是学术化的概念，仅供参考。

1.4 Restful传递参数

HTTP传递参数的三种方式：

• URL：资源定位。适合定位；长度限制。
• QueryString：URL之外的额外数据。灵活；长度限制。
• 请求报文体：供PUT、POST提供数据。灵活；长度不限制；不支持GET、Delete。

1.5 Asp.Net Core如何返回错误码

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

问题：

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

400派：

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

200派：

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

1.6 Asp.Net Core中REST落地指南

• 控制器上 [Route("[controller]/[action]")]

• 强制要求控制器中不同的操作用不同的方法名

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

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

1.7 实践

    [Route("api/a/v1")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        [HttpGet]
        [Route("value/{id}")]
        public IActionResult Get(int id)
        {
            return Ok($"服务A====={id}=====获取成功");
        }

        [HttpPost]
        [Route("value")]
        public IActionResult Post([FromBody] AddValueRequest req)
        {
            return Ok($"服务A====={req}=====添加成功");
        }
        [HttpPut]
        [Route("value/{id}")]
        public IActionResult Put([FromRoute] int id, [FromBody] UpdateValueRequest req)
        {
            return Ok($"服务A====={id}=====修改成功");
        }
        [HttpDelete]
        [Route("value/{id}")]
        public IActionResult Delete(int id)
        {
            return Ok($"服务A====={id}=====删除成功");
        }
    }

    public record AddValueRequest(string UName,int Age,string Email);
    public record UpdateValueRequest(string UName,int Age,string Email);