使用 .NET Core 3.x 构建 RESTFUL Api

准备工作：在此之前你需要了解关于.NET .Core的基础，前面几篇文章已经介绍：https://www.cnblogs.com/hcyesdo/p/12834345.html

首先需要明确一点的就是REST Api它不是一个标准，而是一种架构风格

什么是WebApi?

WebApi通常是指“使用HTTP协议并通过网络调用的API”，由于它使用了HTTP协议，所以需要通过URI信息来指定端点。

WebApi就是一个Web系统，通过访问URI可以与其进行信息交互。

而常用的MVC模式是主要用来构建UI的架构模式。

特点：松耦合，关注点分离、MVC不是一个完整的应用程序框架

MVC映射为API呢？

Model：它赋值处理程序数据的逻辑

View：它是程序里复制展示数据的那部分。构建API的时候，VView就是数据或资源的展示。通常使用JSON格式。

Controller，它复负责View和Model之间的交互。

需要注意的是，在配置服务的时候在core3.0以前可能写的是AddMvc，但是这个服务涉及了View视图以及TagHelper的一些功能，所以在做WebApi的时候用不到

public void ConfigureServices(IServiceCollection services)
{
            //services.AddMvc(); core 3.0以前是这样写的，这个服务包括了    TageHelper等 WebApi不需要的东西，所有3.0以后可以不这样写
            services.AddControllers();
            
}

注意配置中间件的区域管道顺序不能随意改动。

管道就是客户端通过一些指令指向服务器端，在这个过程中呢，会经过一些手动配置的中间件，比如说路由中间件、静态资源中间件等，从客户端出发到服务器端，将数据处理后，再由服务器端原路返回到客户端这样的一个过程。但是在请求的过程中也不排除中间件出现短路的情况，这样也就不会进入到第二个中间件了，而是直接返回到客户端。

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
}

API对外合约：API消费者需要使用到三个概念

• 资源的标识（URI）
• HTTP方法（GET、POST）
• 有效载荷

API对外提供统一资源接口，业界对RESTful资源命名也有规则

关于RESTful API约束

使用名词而不是动词

需求：“我想获得系统里的所有用户”

常见错误：api/getusers

分析：这里的“获取”就是一个动词，而我们的目的应该是“用户”，即用户是一个名词

正确做法：GET api/user

要体现资源的结构/关系

通过id获取单个用户应该是:api/user/{userId}，而不是 api/user/users。这样写就是让API具有很好的可读性和可预测性

需求案例1：

系统存在两个资源：Company(公司)、Employee(员工)，现在需要获取某个公司下的所有员工

分析：应该使用HTTP GET。API在设计的时候需要体现公司与员工的一个包含关系

常见错误做法：api/employees，api/employee/{companyId} 。这两个URI都没有体现公司和员工的一个包含关系

建议做法：api/companies/{companyId}/employees

 

需求案例2：

需要获取某个公司下的某个员工

常见错误做法：api/employees/{employeeId}

建议做法：api/companies/{companyId}/employees/{employeeId}

 

自定义查询怎么命名？

需求：获取所有用户信息，并且按年龄从大到小排序

常见错误做法：api/user/orderby/age

建议做法：api/user?orderby=age （通过QueryString查询字符串，多条件使用 & 符号）

 

HTTP状态码

请求是否成功？如果请求失败了，谁来为此负责

2xx 开头状态码

200 - OK，表示请求成功

201 - Created，表示请求成功并创建了资源

204 - No Content，请求成功，但是不应该返回任何对象，例如删除操作

3xx 开头状态码

用于跳转。例如告诉浏览器搜索引擎，某个页面的网址已经永久改变，绝大多数的WebApi都不需要这类的状态码

4xx 开头：客户端错误

400 - Bad Request，表示API消费者发送到服务器的请求是有错误的

401 - Unauthorized，表示没有提供授权信息或者提供的授权信息有误

403 - Forbidden，表示身份认证已经通过，但是已认证的用户却无法访问请求的资源

404 - NotFound，表示请求的资源不存在

405 - Method not allowed，当尝试发送请求到资源的时候，使用了不被支持的HTTP方法

406 - Not acceptable，表示API消费者请求的表述格式并不被WebApi所支持，并且API不会提供默认的表述格式

5xx 开头状态码

500 - Internal serever error，表示服务器出现了错误，客户端无能为力，只能以后再试试

还有就是RESTful API 返回的结果不一定Json格式的

关于如何标注路由属性 uri ？

先看控制器代码：

using Microsoft.AspNetCore.Mvc;
using Routine.Api.Service;
using System;
using System.Threading.Tasks;

namespace Routine.Api.Controllers
{
    [ApiController] //好处：ApiController不是强制的
                    //1.会启用使用属性路由（Attribute Routing）
                    //2.自动HTTP 400响应
                    //3.推断参数的绑定源
                    //4.Multipart/form-data 请求推断
                    //5.错误状态代码的问题详细信息
    [Route("api/companies")]    //写法一
    //[Route("api/[controller]")]   //写法二：意思是相当于刨除了Controller后缀，获取前面的 Companies C可以是小写，如果你改名了那么你路由的uri也跟着变了（不建议这样写）
    public class CompaniesController:ControllerBase
    {
        private readonly ICompanyRepository _companyRepository;
        public CompaniesController(ICompanyRepository companyRepository)
        {
            _companyRepository = companyRepository ?? 
                                 throw new ArgumentNullException(nameof(companyRepository));
        }
        [HttpGet]
        //IActionResult定义了一些合约，它可以代表ActionResult返回的结果
        public async Task GetCompanies()
        {
            var companies =await _companyRepository.GetCompaniesAsync();//读取出来的是List
            return Ok(companies); 
        }

        [HttpGet("{companyId}")] // Controller标注了ApiController => uri=> api/companies/{companyId}
        public async Task GetCompany(Guid companyId)
        {
            //判断该公司是否存在方法一：这种方法在处理并发请求时可能会出现错误，原因是查到之后，进行删除，进入company后也可能是404找不到了
            //var exists =await _companyRepository.CompanyExistsAsync(compamyId);
            //if (!exists)
            //{
            //    //不存在应该返回404
            //    return NotFound();
            //}
            var company = await _companyRepository.GetCompanyAsync(companyId);//读取出来的是List
            //方法二
            if (company==null)
            {
                return NotFound();
            }
            return Ok(company);
        }
    }
}

为了更好的构建RESTful API 对于 uri 的设计规则也有很严格的要求。

在控制器标注 ApiController，它会自动启用路由属性

通过 [Route] 设计路由规则

比如：接口一：GetCompanies，请求的方式：GET，通过Route 去设置路由规则 [Router("api/companies")]，即查询所有公司信息

[Router("api/companies")] => api/companies

接口二：GetCompany，请求方式：GET，只不过在 添加了 [HTTPGET（"{companyId}"）] =>api/companies/{companyId}，即查询某一公司的信息

关于第二种路由写法请看注释

通过Postman工具测试一下

测试一：接口一

测试二：接口二

以上两个接口测试完毕！！！

对于ASP.NET Core 3.x以前对于 404 NotFound请求状态码输出的格式不太友好，而ASP.NET Core 3.x对于404请求状态码也做了友好的提示。

现在将接口伪造错误信息，提示 404 如图：

关于构建 RESTful API 存在的内容协商：

所谓内容协商就是这样一个过程，针对一个响应，当有多种表述格式可用时，选取最佳的一种表述格式，这些表述可以是XML，JSON，甚至是自定义的格式规则

Accept Header：负责指定输出类型

Media Type（媒体类型）

• application/json
• application/xml

404 Not Acceptable

输出格式：ASP.NET Core 里面对应的就是 Output Formatters 我们称为：输出类型的格式化器

也就是说如果一个API消费者，设置了Accept Header的媒体类型为Json，那么这个RESTful API也应该返回的是JSON，

但是呢如果服务器只接收XML的格式，这个时候请求的媒体类型不被服务器所接受，那么就会返回 406 这个状态码

总而言之，尽量避免不写Accept Header，避免客户端和服务器端接收和返回的类型不一致导致错误。

有输出那么就会有输入了！！！

Content-Type-Header：负责指定输入

Media Type（媒体类型）

• application/json
• application/xml

输出格式：ASP.NET Core里面对应的就是 Input Formatters

比如说：对于一个客户端的POST请求，即添加资源信息，那么就需要输入参数，这些参数可能是放在Body里面，那么在Body里面的这些参数可能是对象的那种格式。那么我们就需要通过 Content-Type-Header来确定Body里面的参数是什么样的类型，可能是Json也可能是Xml或者是自定义的格式，指明之后，RESTful API才能更好的对这些参数进行处理。

看Startup类代码：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Formatters;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Routine.Api.Data;
using Routine.Api.Service;

namespace Routine.Api
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            //services.AddMvc(); core 3.0以前是这样写的，这个服务包括了TageHelper等 WebApi不需要的东西，所有3.0以后可以不这样写
            services.AddControllers(setup =>
            {
                //setup.ReturnHttpNotAcceptable=false;//如果客户端默认为xml格式，服务器端为json，false就不会返回406
                setup.ReturnHttpNotAcceptable = true;//如果请求的类型和服务器请求的类型不一致就返回406
               
                //setup.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter());
                //setup.OutputFormatters.Insert(0, new XmlDataContractSerializerOutputFormatter());
            }).AddXmlDataContractSerializerFormatters();

            //配置接口服务:涉及到这个服务注册的生命周期这里采用AddScoped，表示每次的Http请求
            services.AddScoped();

            //获取配置文件中的数据库字符串连接
            var sqlConnection = Configuration.GetConnectionString("SqlServerConnection");

            //配置上下文类DbContext，因为它本身也是一套服务
            services.AddDbContext(options =>
            {
                options.UseSqlServer(sqlConnection);
            });
        }
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

setup.ReturnHttpNotAcceptable就是处理是在客户端与服务器端数据产生冲突时，是否要即将产生 406 的状态码。

• true：产生
• false：不产生

setup.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter())

分析：实际上OutputFormatters 是一个集合 ，通过Add方法添加服务器允许接受XML格式的数据功能。因为集合中默认只有Json

setup.OutputFormatters.Insert(0,new XmlDataContractSerializerOutputFormatter())

分析：实际上刚刚写的是一种方法。Insert就是指明格式顺序，默认是JSON，通过Insert设置 0 ，就是指明XML为默认接受的数据格式

实际上以上两种写法都是 ASP.NET Core 3.x以前的写法。

ASP.NET Core 3.x的实际写法：就是在AddControllers后面添加XmlDataContractSerializerOutputFormatter方法。这样不管是输入输出都已经设置好了XML的格式数据

postman接口测试：取消setup.OutputFormatters.Insert(0,new XmlDataContractSerializerOutputFormatter())的注释

默认xml：

最后，关于构建RESTFUL Api的URI规则及原理

动作	HTTP方法	请求的参数（Payload）	参数位置	URI	请求前	请求后	响应内容
查询	GET	查询参数	可含查询字符串（QueryString）	/api/companies/{companyId} /api/companies	无修改		单个资源 多个资源的集合
创建/添加	POST	要创建的单个资源信息	Body	/api/companies	旧	新	新创建的单个资源
局部修改/更新	PATCH	待修改的资源 JsonPatchDocument	Body	/api/companies/{companyId}	a:1 b:2	a:1 b:3	无须返回
替换	PUT	要替换的单个资源信息	Body	/api/companies/{companyId}	a:1 b:2	a:2 b:3	无须返回
使用预定义的表示进行创建	PUT	要创建的单个资源信息	Body	/api/companies/{companyId}	旧	新	返回新创建的资源
移除/删除	DELETE	无	可含查询字符串(QueryString)	/api/companies/{companyId}	a b	a	无须返回

.NET Core 3.x构建RESTful API 待续！！！