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

時間  2020-08-17
標籤 使用 core 3.x 構建 restful api 第三 部分 欄目 快樂工作 简体版
原文   原文鏈接

關於HTTP HEAD 和 HTTP GET：數據庫

從執行性能來講，這兩種其實並無什麼區別。最大的不一樣就是對於HTTP HEAD 來講，Api消費者請求接口數據時，若是是經過HTTP HEAD的方式去請求，api

應該是不會把 Body返回回去的。那麼它會返回什麼呢？ 好比說，Headers的一些響應頭數據，例如Content-Type的一些資源信息。而HTTP GET是會將安全

Body裏面的數據返回的。所以，能夠經過HTTP HEAD去檢測該 Api 是否存在資源，換一種說法就是該 Api 是否可用。 app

關於如何給 Api 傳遞數據：async

數據能夠經過多種方式傳遞給 Api！ide

事實上，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，測試成功！

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程