第6章 6.3 Restful风格

 6.3.1 什么是Restful

杨老师讲课PPT：HTTP的设计哲学包含以下几个重点内容

书上说：REST（representational State transfer 表现层状态转移）原则提倡HTTP的语义使用HTTP，如果一个系统符合REST原则，我们就说这个系统是Restful风格的，与之对应的是RPC风格。

6.3.2 Restful的优缺点

RestfI更符合 HTTP 设计的语义，因此我们把接口设计成Restful风格有如下的优点。
(1)所有的资源都尽量通过URL来表示，避免通过 QueryString、报文体来对资源进行定
位，这样 URL 的语义性更清晰。
(2)对所有类型资源的新增、删除、修改、查询操作都统一为向资源发送 POST、DELETE.
PUT、GET请求，接口统一且具有自描述性，减少了开发人员对接口文档的依赖性。
(3)对于 GET、PUT、DELETE 等幂等的操作，网关、网络请求组件等可以对失败的请
求自动重试。
(4)网关等可以对 GET请求进行缓存，能够提升系统的访问速度，而且降低服务器的压力。
(5)通过 HTTP 状态码反映服务器端的处理结果，能够统一错误码，避免自定义错误码带来
的不统一的问题。客户端也可以根据错误码进行统一处理，比如对于403 状态码，客户端统-
提示用户去登录。
(6)网关等系统可以根据状态码来分析系统的访问数据，比如可以根据 HTTP 状态码分析有
多少成功的请求，有多少失败的请求。

Restful风格的接口虽然有很多优点，但是也有如下的缺点。
(1)真实系统中的资源非常复杂，很难清晰地进行资源的划分，因此Restfu风格对设计
人员的IT技能和业务知识的水平要求都非常高。

(2)真实系统中的业务很复杂，并不是所有的操作都能简单地对应到 PUT、GET、DELETE
POST上。而且对于同一个资源的同一个HTTP 谓词有时候有多个业务逻辑，比如“删除id=g
的用户”和“删除 usemmame=yzk的用户”这两个逻辑，如果按照 Restful 风格，我们就要设计
“users/8”和“usersusemame/yzk”这两个地址，这样的地址会让开发人员迷惑，开发人员可
能习惯的仍然是“users/DeleteById/8”“users/DeleteById?id=8”“users/DeleteByUserName/yzk
users/DeleteByUserName?usemmame=yzk”等能清晰地反映操作意图的地址。
(3)真实系统是在不断进化的，一个操作最开始的时候被设计为幂等的PUT，但是后来
的版本又修改了逻辑，可能该操作就变成了不幂等的。如果调用者继续对这个操作进行重试
可能会有副作用。
(4)在 Restful 中，资源尽量通过 URL来定位，要尽量避免使用 QueryString 及请求报文
体传递数据。比如要查询id=8的用户,我们就要使用“Users/8”这样的地址;要査询 name-yzk
的用户，我们就要使用“users/name/yzk”这样的地址;如果要查询班级编号为8并且年龄等
于18岁的学生，我们就要使用“students/class/8/age/18”这样的地址。这样的地址格式是英文
的表达方式，并不符合中文的表达习惯，因此这样写会让很多开发人员迷惑，习惯使用中文的
开发人员可能更习惯通过 OueryString 或者通过请求报文体传递数据。
(5)HTTP状态码的个数是有限的，特别是用于表示业务相关的错误码主要在 4xx 状态码
段中,而业务系统中的错误非常复杂,仅通过 HTTP 状态码来反映错误有时候会无法满足要求。
(6)有一些宽带运营商、路由器、浏览器会对非200 状态码的响应报文进行篡改。比如,
作者就遇到过宽带运营商把状态码为 404 的响应报文篡改为了广告内容。当然，目前大部分正
规的系统都是通过 HTTPS 部署网站的，因此不太可能遇到这个问题。
(7)有的客户端是不支持PUT、DELETE 请求的，比如旧版本的支付宝小程序、一些旧
版浏览器等就不支持PUT、DELETE请求。据说，还有开发人员遇到过一些地区的小运营商
的网络设备不支持 PUT、DELETE 请求的情况。

总结一下就是，一般的开发工作中，并不用完全遵守Restful风格，学会取舍，高效高质量推进开发工作才是王道。就像写作业一样，写正确>写完>写好看，优雅也要有分寸，雅到极致不风流。

6.3.3 Restful中如何传递参数

6.3.4 返回错误码：2XX与4XX

6.3.5 Restful实现指南

非常重要的开发WebAPI的技术点，简单、易上手、高效

实操演示，在WebAPI项目中添加控制器【Persons】

RPC风格编写控制器

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;

namespace WebApplicationTest.Controllers
{
    [Route("api/[controller]/[action]")]
    [ApiController]
    public class PersonsController : ControllerBase
    {
        [HttpGet]
        public Person[] GetAllPerson()
        {
            return new Person[] { new Person("牧羊人", 18), new Person("枸杞泡茶",18) };
        }
        [HttpGet]
        public Person GetByID(long userID)
        {
            if (userID == 1)
            {
                return new Person("牧羊人", 18);
            }
            else if (userID == 2)
            {
                return new Person("枸杞泡茶", 18);
            }
            else
            {
                return null;
            }
        }
        /// <summary>
        /// 
        /// </summary>
        /// <param name="p"></param>
        /// <returns>返回结果OK</returns>
        [HttpPost]
        public string[]  AddUser(Person p)
        {
            return new string[] { "OK","老铁紫腚行"};
        }

    }
}

注意控制器的Route编辑

以及操作方法的请求类型

启动调试

Post请求

响应