使用 .NET Core 3.x 构建RESTful Api（第三部分）

关于HTTP HEAD 和 HTTP GET：

从执行性能来说，这两种其实并没有什么区别。最大的不同就是对于HTTP HEAD 来说，Api消费者请求接口数据时，如果是通过HTTP HEAD的方式去请求，

应该是不会把 Body返回回去的。那么它会返回什么呢？ 比如说，Headers的一些响应头数据，例如Content-Type的一些资源信息。而HTTP GET是会将

Body里面的数据返回的。因此，可以通过HTTP HEAD去检测该 Api 是否存在资源，换一种说法就是该 Api 是否可用。 

关于如何给 Api 传递数据：

数据可以通过多种方式传递给 Api！

事实上，Bind Source Attribute 会告诉 Model 的绑定引擎从哪里去找到绑定。

Bind Source Attribute的六种方式：

1. [FromBody]，请求的Body
2. [FromFrom]，请求的Body中的form数据
3. [FromHeader]，请求的Header
4. [FromQuery]，QueryString 参数
5. [FromRoute]，当前请求中的路由参数
6. [FromService]，当做Action参数而注入的服务

默认情况下，ASP .NET Core会使用 Complex Object Model Binder，它会把数据从 Value Provides 那里提取出来

而 Value Provides的顺序是定义好的！

但是，我们在构建 Api 时，通常会使用 [ApiController] 这个 特性类，目的就是为了更好的构建 RESTful Api。

更改后：

1. [FromBody]，通常是用来推断复杂类型参数，例如Post方式提交的数据
2. [FromFrom]，通常是用来推断IFormFile和IFormFileCollection类型的Action参数，例如用来上传单个或多个文件
3. [FromRoute]，用来推断 Action的参数名和路由模板中的参数名一致的情况下
4. [FromQuery]，用来推断其他的Action参数

关于过滤和搜索：

过滤：

实际上这两者在实际的业务中通常应该是搭配使用的。

所谓过滤：就是过滤集合的一是，根据条件返回限定的集合数据

需求案例： 返回所有类型为国有企业的欧洲公司

分析：过滤条件自然是“国有企业”和“欧洲公司”

那么 uri 的设计就会是：GET  api/companies?Type=State-owned&regoin=Europe

所以过滤就是：我们把某个字段的名字和与之匹配的值一起传递给 Api ，并将这些以集合的方式返回

搜索：

搜索实际上超出了过滤的范围，针对搜索我们通常不会把要搜索的字段传递过去，而是只把要搜索的值传递给 Api，

然后 Api 自行决定应该对哪些字段来查找该值，一般是全文搜索

例如：api/companies?q=xxx

如果还不理解？

过滤：根据条件，将某一集合的数据按条件进行移除或选择

搜索：可以是空集合，根据要搜索的值，将数据添加到集合中，再返回

注意：过滤和搜索这些参数并不是资源的一部分。

案例代码：过滤员工性别（参数： genderDisplay）、搜索匹配数据（参数：q）

实现类处理业务逻辑：

分析：

首先第二个if判断，如果都为空，那么就是返回全部数据，什么也没发生。

第二个if判断性别参数是否为空，如果不是，那么就编写过滤性别的代码，在这之前将定义的items就是查询到该公司下的所有员工然后在处理其他事件。

第三个if判断搜索的值是否为空，如果不是，就编写模糊查询的代码，这里是多字段模糊查询

以上if执行完毕后，实际上并没有生成一个完整的 SQL 语句，实际上这样做就是为了性能，最后才通过 ToList返回集合，至于你是过滤还是搜索都无所谓！

public async Task<IEnumerable<Employee>> GetEmployeesAsync(Guid companyId, string genderDisplay, string q)
        {
            if (companyId==Guid.Empty)
            {
                throw new ArgumentNullException(nameof(companyId));
            }
            if (string.IsNullOrWhiteSpace(genderDisplay) || string.IsNullOrWhiteSpace(q))
            {
                return await _context.Employees
                    .Where(x => x.CompanyId == companyId)
                    .OrderBy(x => x.EmployeeNo)
                    .ToListAsync();
            }
            var items = _context.Employees.Where(x => x.CompanyId == companyId);
            if (!string.IsNullOrWhiteSpace(genderDisplay))
            {
                genderDisplay = genderDisplay.Trim();
                var gender = Enum.Parse<Gender>(genderDisplay);
                items = items.Where(x => x.Gender == gender);
            }
            if (!string.IsNullOrWhiteSpace(q))
            {
                q = q.Trim();
                items = items.Where(x => x.EmployeeNo.Contains(q) || x.FirstName.Contains(q) || x.LastName.Contains(q));
            }
            return await items
                .OrderBy(x => x.EmployeeNo)
                .ToListAsync();
        }

控制器调用：

通过[FromQuery]的Name来指定参数匹配的名称是什么，比如：gender或者是genderDisplay

  public async Task<ActionResult<IEnumerable<EmployeeDto>>>
            GetEmployeesForCompany(Guid companyId,[FromQuery(Name = "gender")] string genderDisplay,string q)
        {
            if (! await _companyRepository.CompanyExistsAsync(companyId))
            {
                return NotFound();
            }
            var employees =await _companyRepository.GetEmployeesAsync(companyId, genderDisplay,q);
            var employeeDtos = _mapper.Map<IEnumerable<EmployeeDto>>(employees);
            return Ok(employeeDtos);
        }

接口测试：

还需要考虑一种情况：

在实际业务当中呢，这种搜索过滤的条件肯定不止一两个，一般是多个属性进行搜索或者过滤，这个时候，如果也按照查询字符串的方式传递给 Api ，那么就会显得非常的复杂也很容易写错。

那怎么办呢？

很简单，其实只需要写一个对应的类就好了，把需要查询的字段属性全部放到类里面。

这样就算后期想再增加条件属性只需要编写类里面的代码，无需在，Api 接口中在去增加参数。

添加一个CompanyParameters类：

分析：分别定义公司名称属性字段和全文搜索属性字段

namespace Routine.Api.ResoureParameters
{
    public class CompanyDtoParameters
    {
        public string CompanyName { get; set; }
        public string SearchTerm { get; set; }
    }
}

业务逻辑类：

public async Task<IEnumerable<Company>> GetCompaniesAsync(CompanyDtoParameters companyParameters)
        {
            if (companyParameters==null)
            {
                throw  new ArgumentNullException(nameof(companyParameters));
            }

            if (string.IsNullOrWhiteSpace(companyParameters.CompanyName) &&
                string.IsNullOrWhiteSpace(companyParameters.SearchTerm))
            {
                return await _context.Companies.ToListAsync();
            }
            var queryableCompany = _context.Companies as IQueryable<Company>;
            if (!string.IsNullOrWhiteSpace(companyParameters.CompanyName))
            {
                companyParameters.CompanyName = companyParameters.CompanyName.Trim();
                queryableCompany = queryableCompany.Where(x => x.Name == companyParameters.CompanyName);
            }
            if (!string.IsNullOrWhiteSpace(companyParameters.SearchTerm))
            {
                companyParameters.SearchTerm = companyParameters.SearchTerm.Trim();
                queryableCompany = queryableCompany.Where(x => x.Name.Contains(companyParameters.SearchTerm) ||
                                                               x.Introduction.Contains(companyParameters.SearchTerm));
            }
            return await queryableCompany.ToListAsync();
        }

控制器调用：

注意：需要加上[FromQuery]标记，不然会出现状态码为 415 ，也就是不支持的媒体类型（MediaType）

分析：此时方法的参数是一个类，就相当于它是一个复杂的数据类型，这个时候请求 Api 的时候它可能会认为绑定源是来自于QueryString查询字符串。

所以我们需要手动指定一些绑定源。

 [HttpGet]
 public async Task<ActionResult<IEnumerable<CompanyDto>>> GetCompanies([FromQuery]CompanyDtoParameters companyDtoParameters)
 {
       var companies =await _companyRepository.GetCompaniesAsync(companyDtoParameters);
       var companyDtos = _mapper.Map<IEnumerable<CompanyDto>>(companies);
       return Ok(companyDtos); 
 }

重新测试接口：

接口测试成功！

关于HTTP 方法的安全性与幂等性：

安全性是指方法执行后并不会改变资源的表述，例如 GET 它只是查询获取资源，它并不会改变资源的表述，所以它是安全的。

幂等性是指方法无论执行多少次都会返回得到同样的结果，例如对资源进行修改，而修改的内容是一样的，所以无论修改多少次得到的结果也是一样的，例如 HTTP PUT 就是幂等的。

案例1：如何创建 POST 父资源（Company）：

在创建资源请求之前，首先要明确一个理念，那就是创建资源的 DTO 是否要和 GET 请求查询的 Dto 的属性字段

内容一致呢？

答案是不应该将POST，GET请求使用同一个 Dto 。

其实原因很简单，仔细想想，其实POST Action方法请求的资源大部分业务情况与 GET Action 请求的资源情况是不一样的

尽管有时候可能作为查询的Dto属性和作为创建资源的POST Dto属性一样。这个时候也应该将它们分开使用。

因为在未来业务处理中 DTO 中的属性可能随时都在发生改变。

所以，这样分开写 DTO 的好处就是方便后期的重构。

简单点来说就是针对 查询、创建、更新三大类小块我们都应该使用不同的 DTO。

对 Company 这个 Entity Model做一下 POST 创建资源的请求：

建立 CompanyAddDto类：

using System;

namespace Routine.Api.Models
{
    public class CompanyAddDto
    {
        public string Name { get; set; }
        public string Introduction { get; set; }
    }
}

对比一下GET Action 请求的 Dto ，即 CompanyDto：

实际上两者一般来说属性很可能根据业务情况不一样！！！

using System;

namespace Routine.Api.Models
{
    public class CompanyDto
    {
        public Guid Id { get; set; }
        public string CompanyName { get; set; }
    }
}

注意，别忘记添加 mapper 映射关系了，这里就是从 CompanyAddDto 映射到 Employee（Entity Model），因为是添加到数据库里面。

因为CompanyDto和Company属性字段并没有什么改变，所以不需要对专门的字段进行配置

using AutoMapper;
using Routine.Api.Entities;
using Routine.Api.Models;

namespace Routine.Api.Profiles
{
    public class CompanyProfiles:Profile
    {
        public CompanyProfiles()
        {
            CreateMap<CompanyAddDto, Company>();
        }
    }
}

在控制器添加 POST 请求的方法：

需要注意在资源添加后还需要重新映射回 GET 请求查询资源的 Dto！

[HttpPost]
        public async Task<ActionResult<CompanyDto>> CreateCompany(CompanyAddDto company) //如果 companyAddDto为空，ASP.NET Core会自动返回 400错误，这是因为 [ApiController] Attribute的作用
        {
            //需要将资源映射到 EntityModel
            var entity = _mapper.Map<Company>(company);
            _companyRepository.AddCompany(entity);
            await _companyRepository.SaveAsync();

            //此时添加完成后，返回出去的还是Dto，所有还需要进行一次映射
            var returnDto = _mapper.Map<CompanyDto>(entity);

            //CreatedAtRoute，会返回一些响应头的资源运行我们返回带着一个地址的head，而这个head含有一个uri，例如 201 表示添加成功，还有就是 uri，通过这个uri可以找到这个新创建的资源
            //参数1：生成uri名称，与返回的GET方法名一样，参数2：路由值，参数3：对象值
            return CreatedAtRoute(nameof(GetCompany), new { companyId= returnDto.Id}, returnDto);
        }

关于返回的 CreatedAtRoute方法，注释标注了作用和对应的参数，第一个参数 GetCompany 对应的就是GET Action标注的路由名称，如下：

接下来进行 POST 请求的接口测试，打开 Postman 工具。

返回状态码 201 表示 Post 成功！

再看看Headers里面给我们带回了什么信息：

这实际上就是返回 CreatedAtRoute 方法的作用，会带着刚刚添加的资源的 uri 地址

案例2：如何创建 POST 子资源（Employee）：

创建子资源其实和创建父资源差不多。

同样添加 EmployeeAddDto 类：

using System;
using Routine.Api.Entities;

namespace Routine.Api.Models
{
    public class EmployeeAddDto
    {
        public string EmployeeNo { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public Gender Gender { get; set; }
        public DateTime DateOfBirth { get; set; }
    }
}

再来对比 EmployeeDto：

可以看出这两个类的区别还是很大的

using System;

namespace Routine.Api.Models
{
    public class EmployeeDto
    {
        public Guid Id { get; set; }
        public Guid CompanyId { get; set; }
        public string EmployeeNo { get; set; }
        public string Name { get; set; }
        public string GenderDispaly { get; set; }
        public int Age { get; set; }
    }
}

在控制器添加 POST 请求的方法：

需要注意的是，因为Employee作为子资源所以需要带着 CompanyId 回去

[HttpPost]
        public async Task<ActionResult<EmployeeDto>> CreateEmployeeForCompany(Guid companyId, EmployeeAddDto employee)
        {
            if (!await  _companyRepository.CompanyExistsAsync(companyId))
            {
                return NotFound();
            }
            var entity = _mapper.Map<Employee>(employee);
            _companyRepository.AddEmployee(companyId,entity);
            await _companyRepository.SaveAsync();
            var dtoToReturn = _mapper.Map<EmployeeDto>(entity);
            return CreatedAtRoute(nameof(GetEmployeeForCompany), new
            {
                companyId,
                employeeId = dtoToReturn.Id
            }, dtoToReturn);
        }

接下来进行 POST 请求的接口测试，打开 Postman 工具。

返回201，接口测试成功！

同样来看看 Headers里面返回的一些资源：

将刚刚添加的资源以 uri 形式返回。

案例3：同时创建父子资源：

业务需求：同时创建多个子资源 employee

需要在创建POST Action的Company方法上扩展一下就行了，在 CompanyAddDto中添加Employees属性集合：

最好和Entity Model的 Employee中 Employee一样，这样就无效对这个属性在映射的时候做配置了。

接口测试：

POST 成功 ！

案例4：刚刚添加了多个子资源，那么如何添加多个父资源呢？

这就需要重新写一个 uri ，因为当前 api/companies uri 是针对于单个 Company的 Post 创建资源。

既然重新写一个uri，那么直接创建一个新的控制器，标注 Attribute [ApiController]为 api/companycollections

ConpanyCollectionController控制器代码：

编写一个构造函数的依赖注入，分别注入 AutoMapper 以及 CompanyRepository 业务逻辑类

分析：既然是创建多个Company，那么返回的也是一个 IEnumerable的Dto集合，参数也是一个为 IEnumerable的 CompanyAddDto集合，这没有什么问题。

然后循环添加数据就好了。在此之前还是一样的，需要将 CompanyAddDto 映射到 Entity Model对应的Company 里面！

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using AutoMapper;
using Microsoft.AspNetCore.Mvc;
using Routine.Api.Entities;
using Routine.Api.Models;
using Routine.Api.Service;

namespace Routine.Api.Controllers
{
    [ApiController]
    [Route("api/companycollections")]
    public class CompanyCollectionsController:ControllerBase
    {
        private readonly IMapper _mapper;
        private readonly ICompanyRepository _companyRepository;

        public CompanyCollectionsController(IMapper mapper,ICompanyRepository companyRepository)
        {
            _mapper = mapper ?? throw new ArgumentNullException(nameof(mapper));
            _companyRepository = companyRepository ?? throw  new ArgumentNullException(nameof(companyRepository));
        }

        [HttpPost]
        public async Task<ActionResult<IEnumerable<CompanyDto>>> CreateCompanyCollection(
            IEnumerable<CompanyAddDto> companyCollection)
        {
            var companyEntities = _mapper.Map<IEnumerable<Company>>(companyCollection);
            foreach (var company in companyEntities)
            {
                _companyRepository.AddCompany(company);
            }
            await _companyRepository.SaveAsync();
            return Ok();
        }
    }
}

这里先测试是否会返回一个 Ok 200 的状态码

接口测试：

返回 200，测试成功！