使用 .NET Core 3.x 構建 RESTFUL Api （續）

阿新 • • 發佈：2020-08-11

關於Entity Model vs 面向外部的Model

Entity Framework Core 使用 Entity Model 用來表示資料庫裡面的記錄。

面向外部的Model 則表示要傳輸的東西，有時候被稱為 Dto，有時候被稱為 ViewModel。

關於Dto，API消費者通過Dto，僅提供給使用者需要的資料起到隔離的作用，防止API消費者直接接觸到核心的Entity Model。

可能你會覺得有點多餘，但是仔細想想你會發現，Dto的存在是很有必要的。

Entity Model 與資料庫實際上應該是有種依賴的關係，資料庫某一項功能發生改變，Entity Model也應該會做出相應的動作，那麼這個時候 API消費者在請求伺服器介面資料時，如果直接接觸到了 Entity Model資料，那麼它也就無法預測到底是哪一項功能做出了改變。這個時候可能在做 API 請求的時候發生不可預估的錯誤。Dto的存在一定程度上解決了這一問題。

那麼它的作用是？

系統更加健壯
系統更加可靠
系統易於進化

編寫Company的 Dto：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

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

對比Company的 Entity Model：

using System;
using System.Collections.Generic;
namespace Routine.Api.Entities
{
    /// <summary>
    /// 公司
    /// </summary>
    public class Company
    {
        public Guid Id { get; set; }
        public string Name { get; set; }
        public string Introduction { get; set; }
        public 
 ICollection<Employee> Employees { get; set; }
    }
}

Id和Name屬性是一致的，對於 Employees集合以及 Introduction 字串為了區分，這裡不提供給 Dto

如何使用？

這裡就涉及到了如何從 Entity Model 的資料轉化到 Dto

分析：我們給API消費者提供的資料肯定是一個集合，那麼可以先將Company的Dto定義為一個List集合，再通過迴圈 Entity Model 的資料，將資料新增到集合並且賦值給 Dto 對應的屬性。

控制器程式碼：

[HttpGet]
        //IActionResult定義了一些合約，它可以代表ActionResult返回的結果
public async Task<ActionResult<IEnumerable<CompanyDto>>> GetCompanies()
{
      var companies =await _companyRepository.GetCompaniesAsync();//讀取出來的是List
      var companyDtos = new List<CompanyDto>();
      foreach (var company in companies)
      {
           companyDtos.Add(new CompanyDto
           {
                Id = company.Id,
                Name = company.Name
               });
           };
           return Ok(companyDtos); 
       }
}

這裡你可能注意到了返回的是 ActionResult<T>

關於 ActionResult<T>，好處就是讓 API 消費者意識到此介面的返回型別，就是將介面的返回型別進一步的明確，可以方便呼叫，讓程式碼的可讀性也更高。

你可以返回IEnumerable型別，也可以直接返回List，當然這兩者並沒有什麼區別，因為List也實現了 IEnumerable 這個介面！

那麼這樣做會面臨又一個問題。如果 Dto 需要的資料又20甚至50條往上，那麼這樣寫會顯得非常的笨拙而且也很容易出錯。

如何處理呢？ dotnet生態給我們提供了一個很好的物件屬性對映器 AutoMapper！！！

關於 AutoMapper，官方解釋：基於約定的物件屬性對映器。

它還存在一個作用，在處理對映關係時出現如果出現空引用異常，就是對映的目標型別出現了與源型別不匹配的屬性欄位，那麼就會自動忽略這一異常。

如何下載？

開啟 nuget 工具包，搜尋AutoMapper ，下載第二個！！！ 原因是這個更好的實現依賴注入，可以看到它也依賴於 AutoMapper，相當於把第一個也一併下載了。

如何使用 AutoMapper？

第一步進入 Startup類註冊AutoMapper服務！

public void ConfigureServices(IServiceCollection services)
        {
            //services.AddMvc(); core 3.0以前是這樣寫的，這個服務包括了TageHelper等 WebApi不需要的東西，所有3.0以後可以不這樣寫
            services.AddControllers();

            //註冊AutoMapper服務
            services.AddAutoMapper(AppDomain.CurrentDomain.GetAssemblies());

            //配置介面服務:涉及到這個服務註冊的生命週期這裡採用AddScoped，表示每次的Http請求
            services.AddScoped<ICompanyRepository, CompanyRepository>();

            //獲取配置檔案中的資料庫字串連線
            var sqlConnection = Configuration.GetConnectionString("SqlServerConnection");

            //配置上下文類DbContext，因為它本身也是一套服務
            services.AddDbContext<RoutineDbContext>(options =>
            {
                options.UseSqlServer(sqlConnection);
            });
        }

關於 AddAutoMapper() 方法，實際上它需要返回一個程式集陣列，就是AutoMapper的執行配置檔案，那麼通過 GetAssemblies 去掃描AutoMapper下的所有配置檔案即可。

第二步：建立處理 AutoMapper 對映類

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

namespace Routine.Api.Profiles
{
    public class CompanyProfiles:Profile
    {
        public CompanyProfiles()
        {
            //新增對映關係，處理源型別與對映目標型別屬性名稱不一致的問題
            //引數一：源型別，引數二：目標對映型別
            CreateMap<Company, CompanyDto>()
                .ForMember(target=>target.CompanyName,
                    opt=> opt.MapFrom(src=>src.Name));
        }
    }
}

分析：通過CreateMap，對於引數一：源型別，引數二：目標對映型別。

關於 ForMember方法的作用，有時候你得考慮一個情況，前面已經說過，AutoMapper 是基於約定的物件到物件（Object-Object）的屬性對映器，如果所對映的屬性欄位不一致一定是無法對映成功的！

約定即屬性欄位與源型別屬性名稱須一致！！！但是你也可以處理這一情況的發生，通過lambda表示式，將目標對映型別和源型別關係重對映即可。

第三步：開始資料對映

先來看對映前的程式碼：通過集合迴圈賦值：

[HttpGet]
        //IActionResult定義了一些合約，它可以代表ActionResult返回的結果
        public async Task<ActionResult<IEnumerable<CompanyDto>>> GetCompanies()
        {
            var companies =await _companyRepository.GetCompaniesAsync();//讀取出來的是List

            var companyDtos = new List<CompanyDto>();
            foreach (var company in companies)
            {
                companyDtos.Add(new CompanyDto
                {
                    Id = company.Id,
                    Name = company.Name
                });
            }
            return Ok(companyDtos); 
        }

通過 AutoMapper對映：

[HttpGet]
        //IActionResult定義了一些合約，它可以代表ActionResult返回的結果
        public async Task<ActionResult<IEnumerable<CompanyDto>>> GetCompanies()
        {
            var companies =await _companyRepository.GetCompaniesAsync();//讀取出來的是List

            var companyDtos = _mapper.Map<IEnumerable<CompanyDto>>(companies);
            return Ok(companyDtos); 
        }

分析：Map()方法處理需要返回的目標對映型別，然後帶入源型別。

關於獲取父子關係的資源：

所謂父：Conmpany（公司）、子：Employees（員工）

可能你注意到了基本上就是主從表的引用關係

那麼我們在設計AP uri 的時候也需要考慮到這一點

需求案例 1：查詢某一公司下的所有員工資訊

分析：設計到員工資訊，也需要需要實現 Entity Model 對 EmployeeDtos 的轉換，所以需要建立 EmployeeDto

對比 Employee 的 Entity Model和EmployeeDto

Entity Model 程式碼：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace Routine.Api.Entities
{
    /// <summary>
    /// 員工
    /// </summary>
    public class Employee
    {
        public Guid Id { get; set; }
        //公司外來鍵
        public Guid CompanyId { get; set; }
        //公司表導航屬性
        public Company Company { get; set; }
        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 程式碼：

分析：對性別 Gender 列舉型別做了處理，改成了string型別，方便呼叫。另外對於姓名 Name 也是將 FirstName 和 LastName合併，年齡 Age 改成了 int型別

那麼，這些改動我們都需要在 EmployeeProfile類中在對映時進行標註，不然由於物件屬性對映器的約定，無法進行對映！！！

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; }
    }
}

EmployeeProfile類程式碼：

邏輯和 CompanyProfile類的對映是一樣的

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

namespace Routine.Api.Profiles
{
    public class EmployeeProfile:Profile
    {
        public EmployeeProfile()
        {
            CreateMap<Employee, EmployeeDto>()
                .ForMember(target => target.Name,
                    opt => opt.MapFrom(src => $"{src.FirstName} {src.LastName}"))
                .ForMember(target=>target.GenderDispaly,
                    opt=>opt.MapFrom(src=>src.Gender.ToString()))
                .ForMember(target=>target.Age,
                    opt=>opt.MapFrom(src=>DateTime.Now.Year-src.DateOfBirth.Year));
        }
    }
}

接下來開始建立 EmployeeController 控制器，來通過對映器實現對映關係

EmployeeController ：

需要注意 uir 的設計，我們查詢的是某一個公司下的所有員工資訊，所以也需要是 Entity Model 對 EmployeeDtos的轉換，同樣是藉助物件屬性對映器。

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

namespace Routine.Api.Controllers
{

    [ApiController]
    [Route("api/companies/{companyId}/employees")]
    public class EmployeesController:ControllerBase
    {
        private readonly IMapper _mapper;
        private readonly ICompanyRepository _companyRepository; 
        public EmployeesController(IMapper mapper, ICompanyRepository companyRepository)
        {
            _mapper = mapper ?? throw new ArgumentNullException(nameof(mapper));
            _companyRepository = companyRepository ?? throw new ArgumentNullException(nameof(companyRepository));
        }
        [HttpGet]
        public async Task<ActionResult<IEnumerable<EmployeeDto>>> GetEmployeesForCompany(Guid companyId)
        {
            if (! await _companyRepository.CompanyExistsAsync(companyId))
            {
                return NotFound();
            }
            var employees =await _companyRepository.GetEmployeesAsync(companyId);
            var employeeDtos = _mapper.Map<IEnumerable<EmployeeDto>>(employees);
            return Ok(employeeDtos);
        }
    }
}

介面測試（某一公司下的所有員工資訊）：

需求案例 2：查詢某一公司下的某一員工資訊

來想想相比需求案例1哪些地方需要進行改動的？

既然是某一個員工，說明 uir 需要加個員工的引數 Id進去。

還有除了判斷該公司是否存在，還需要判斷該員工是否存在。

另外，既然是某一個員工，所以返回的應該是個物件而非IEnumable集合。

程式碼：

[HttpGet("{employeeId}")]
        public async Task<ActionResult<EmployeeDto>> GetEmployeeForCompany(Guid companyId,Guid employeeId)
        {
            //判斷公司存不存在
            if (!await _companyRepository.CompanyExistsAsync(companyId))
            {
                return NotFound();
            }
            //判斷員工存不存在
            var employee = await _companyRepository.GetEmployeeAsync(companyId, employeeId);
            if (employee==null)
            {
                return NotFound();
            }
            //對映到 Dto
            var employeeDto = _mapper.Map<EmployeeDto>(employee);
            return Ok(employeeDto);
        }

介面測試（某一公司下的某一員工資訊）：

可以看到測試成功！

關於故障處理：

這裡的“故障”主要是指伺服器故障或者是丟擲異常的故障，ASP.NET Core 對於伺服器故障一般會引發 500 狀態碼錯誤，對於這種錯誤，會導致一種後果就是在出現故障後

故障資訊會將程式異常細節顯示出來，這就對API消費者不夠友好，而且也造成一定的安全隱患。但此後果是在開發環境下產生也就是Development。

當然ASP.NET Core開發團隊也意識到了這種問題！

偽造程式異常：

引發異常後接口測試：

可以看到此異常已經暴露了程式細節給 API 消費者，這種做法欠妥。

怎麼辦呢？ 試試改一下開發的環境狀態！

重新測試介面：

問題解決！

但是你可能想根據這些異常丟擲一些自定義的資訊給 API 消費者實際上也可以。

回到 Stratup 類：新增一箇中間件 app.UseExceptionHandler即可

分析：意思是如果有未處理的異常發生的時候就會走 else 裡面的程式碼，實際專案中這一塊需要記錄一下日誌

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler(appBulider =>
                {
                    appBulider.Run(async context =>
                    {
                        context.Response.StatusCode = 500
                        await context.Response.WriteAsync("The program Error!");
                    });
                });
            }
            app.UseRouting();

            app.UseAuthorization();

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

再來測試一下介面是否成功返回自定義異常資訊：

測試成功！！！

使用 .NET Core 3.x 構建 RESTFUL Api （續）

使用 .NET Core 3.x 構建 RESTFUL Api （續）

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

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

基於 Aspect-Injector 以及 .NET CORE 3.1 實現AOP程式設計（一）

【.Net Core】使用 Nginx 釋出 .Net Core 3.1 專案至LInux（Centos7）。

ASP.NET Core 3.x RESTful API學習記錄--輸入驗證：IValidatableObject

IdentityServer4與API單專案整合（net core 3.X）

ASP.NET Core 3.x啟動時執行非同步任務（一）

.Net Core 3.x Api開發筆記 -- Starup入門(二)

.Net Core 3.x Api學習筆記 -- IOC,使用Autofac實現依賴注入(三)

.Net Core 3.x Api開發筆記 -- 讀取配置檔案資訊(四)

.Net Core微服務入門全紀錄（四）——Ocelot-API閘道器（上）

如何在 asp.net core 3.x 的 startup.cs 檔案中獲取注入的服務

gRPC by .net core 3.x——概念、語法、編譯

ASP.NET Core 3.1使用Swagger API介面文件

01 .net core 3.x 啟動順序

ASP.NET Core 3.x控制IHostedService啟動順序淺探

.NET Core 3.x 基於Autofac的AOP快取

.NET Core 3.x 基於AspectCore實現AOP，實現事務、快取攔截器

ASP.NET Core 3.x [FromBody] 傳遞 Json 字串

使用 .NET Core 3.x 構建 RESTFUL Api （續）

相關推薦