ASP.NET Core Web API 最佳實踐指南

原文地址： ASP.NET-Core-Web-API-Best-Practices-Guide

介紹#

當我們編寫一個項目的時候，我們的主要目標是使它能如期運行，並盡可能地滿足所有用戶需求。

但是，你難道不認為創建一個能正常工作的項目還不夠嗎？同時這個項目不應該也是可維護和可讀的嗎？

事實證明，我們需要把更多的關注點放到我們項目的可讀性和可維護性上。這背后的主要原因是我們或許不是這個項目的唯一編寫者。一旦我們完成后，其他人也極有可能會加入到這里面來。

因此，我們應該把關注點放到哪里呢？

在這一份指南中，關於開發 .NET Core Web API 項目，我們將敘述一些我們認為會是最佳實踐的方式。進而讓我們的項目變得更好和更加具有可維護性。

現在，讓我們開始想一些可以應用到 ASP.NET Web API 項目中的一些最佳實踐。

Startup 類 和 服務配置#

STARTUP CLASS AND THE SERVICE CONFIGURATION

在 Startup 類中，有兩個方法：ConfigureServices 是用於服務注冊，Configure 方法是向應用程序的請求管道中添加中間件。

因此，最好的方式是保持 ConfigureServices 方法簡潔，並且盡可能地具有可讀性。當然，我們需要在該方法內部編寫代碼來注冊服務，但是我們可以通過使用 擴展方法 來讓我們的代碼更加地可讀和可維護。

例如，讓我們看一個注冊 CORS 服務的不好方式：

Copy

public void ConfigureServices(IServiceCollection services) { services.AddCors(options => { options.AddPolicy("CorsPolicy", builder => builder.AllowAnyOrigin() .AllowAnyMethod() .AllowAnyHeader() .AllowCredentials()); }); }

盡管這種方式看起來挺好，也能正常地將 CORS 服務注冊成功。但是想象一下，在注冊了十幾個服務之后這個方法體的長度。

這樣一點也不具有可讀性。

一種好的方式是通過在擴展類中創建靜態方法：

Copy

public static class ServiceExtensions { public static void ConfigureCors(this IServiceCollection services) { services.AddCors(options => { options.AddPolicy("CorsPolicy", builder => builder.AllowAnyOrigin() .AllowAnyMethod() .AllowAnyHeader() .AllowCredentials()); }); } }

然后，只需要調用這個擴展方法即可：

Copy

public void ConfigureServices(IServiceCollection services) { services.ConfigureCors(); }

了解更多關於 .NET Core 的項目配置，請查看：.NET Core Project Configuration

項目組織#

PROJECT ORGANIZATION

我們應該嘗試將我們的應用程序拆分為多個小項目。通過這種方式，我們可以獲得最佳的項目組織方式，並能將關注點分離（SoC）。我們的實體、契約、訪問數據庫操作、記錄信息或者發送郵件的業務邏輯應該始終放在單獨的 .NET Core 類庫項目中。

應用程序中的每個小項目都應該包含多個文件夾用來組織業務邏輯。

這里有個簡單的示例用來展示一個復雜的項目應該如何組織：

基於環境的設置#

ENVIRONMENT BASED SETTINGS

當我們開發應用程序時，它處於開發環境。但是一旦我們發布之后，它將處於生產環境。因此，將每個環境進行隔離配置往往是一種好的實踐方式。

在 .NET Core 中，這一點很容易實現。

一旦我們創建好了項目，就已經有一個 appsettings.json 文件，當我們展開它時會看到 appsettings.Development.json 文件：

此文件中的所有設置將用於開發環境。

我們應該添加另一個文件 appsettings.Production.json，將其用於生產環境：

生產文件將位於開發文件下面。

設置修改后，我們就可以通過不同的 appsettings 文件來加載不同的配置，取決於我們應用程序當前所處環境，.NET Core 將會給我們提供正確的設置。更多關於這一主題，請查閱：Multiple Environments in ASP.NET Core.

數據訪問層#

DATA ACCESS LAYER

在一些不同的示例教程中，我們可能看到 DAL 的實現在主項目中，並且每個控制器中都有實例。我們不建議這么做。

當我們編寫 DAL 時，我們應該將其作為一個獨立的服務來創建。在 .NET Core 項目中，這一點很重要，因為當我們將 DAL 作為一個獨立的服務時，我們就可以將其直接注入到 IOC（控制反轉）容器中。IOC 是 .NET Core 內置功能。通過這種方式，我們可以在任何控制器中通過構造函數注入的方式來使用。

Copy

public class OwnerController: Controller { private IRepository _repository; public OwnerController(IRepository repository) { _repository = repository; } }

控制器#

CONTROLLERS

控制器應該始終盡量保持整潔。我們不應該將任何業務邏輯放置於內。

因此，我們的控制器應該通過構造函數注入的方式接收服務實例，並組織 HTTP 的操作方法（GET，POST，PUT，DELETE，PATCH...）:

Copy

public class OwnerController : Controller { private readonly ILoggerManager _logger; private readonly IRepository _repository; public OwnerController(ILoggerManager logger, IRepository repository) { _logger = logger; _repository = repository; } [HttpGet] public IActionResult GetAllOwners() { } [HttpGet("{id}", Name = "OwnerById")] public IActionResult GetOwnerById(Guid id) { } [HttpGet("{id}/account")] public IActionResult GetOwnerWithDetails(Guid id) { } [HttpPost] public IActionResult CreateOwner([FromBody]Owner owner) { } [HttpPut("{id}")] public IActionResult UpdateOwner(Guid id, [FromBody]Owner owner) { } [HttpDelete("{id}")] public IActionResult DeleteOwner(Guid id) { } }

我們的 Action 應該盡量保持簡潔，它們的職責應該包括處理 HTTP 請求，驗證模型，捕捉異常和返回響應。

Copy

[HttpPost] public IActionResult CreateOwner([FromBody]Owner owner) { try { if (owner.IsObjectNull()) { return BadRequest("Owner object is null"); } if (!ModelState.IsValid) { return BadRequest("Invalid model object"); } _repository.Owner.CreateOwner(owner); return CreatedAtRoute("OwnerById", new { id = owner.Id }, owner); } catch (Exception ex) { _logger.LogError($"Something went wrong inside the CreateOwner action: { ex} "); return StatusCode(500, "Internal server error"); } }

在大多數情況下，我們的 action 應該將 IActonResult 作為返回類型（有時我們希望返回一個特定類型或者是 JsonResult ...）。通過使用這種方式，我們可以很好地使用 .NET Core 中內置方法的返回值和狀態碼。

使用最多的方法是：

• OK => returns the 200 status code
• NotFound => returns the 404 status code
• BadRequest => returns the 400 status code
• NoContent => returns the 204 status code
• Created, CreatedAtRoute, CreatedAtAction => returns the 201 status code
• Unauthorized => returns the 401 status code
• Forbid => returns the 403 status code
• StatusCode => returns the status code we provide as input

處理全局異常#

HANDLING ERRORS GLOBALLY

在上面的示例中，我們的 action 內部有一個 try-catch 代碼塊。這一點很重要，我們需要在我們的 action 方法體中處理所有的異常（包括未處理的）。一些開發者在 action 中使用 try-catch 代碼塊，這種方式明顯沒有任何問題。但我們希望 action 盡量保持簡潔。因此，從我們的 action 中刪除 try-catch ,並將其放在一個集中的地方會是一種更好的方式。.NET Core 給我們提供了一種處理全局異常的方式，只需要稍加修改，就可以使用內置且完善的的中間件。我們需要做的修改就是在 Startup 類中修改 Configure 方法：

Copy

public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { app.UseExceptionHandler(config => { config.Run(async context => { context.Response.StatusCode = 500; context.Response.ContentType = "application/json"; var error = context.Features.Get<IExceptionHandlerFeature>(); if (error != null) { var ex = error.Error; await context.Response.WriteAsync(new ErrorModel { StatusCode = 500, ErrorMessage = ex.Message }.ToString()); } }); }); app.UseRouting(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); }); }

我們也可以通過創建自定義的中間件來實現我們的自定義異常處理：

Copy

// You may need to install the Microsoft.AspNetCore.Http.Abstractions package into your project public class CustomExceptionMiddleware { private readonly RequestDelegate _next; private readonly ILogger<CustomExceptionMiddleware> _logger; public CustomExceptionMiddleware(RequestDelegate next, ILogger<CustomExceptionMiddleware> logger) { _next = next; _logger = logger; } public async Task Invoke(HttpContext httpContext) { try { await _next(httpContext); } catch (Exception ex) { _logger.LogError("Unhandled exception....", ex); await HandleExceptionAsync(httpContext, ex); } } private Task HandleExceptionAsync(HttpContext httpContext, Exception ex) { //todo return Task.CompletedTask; } } // Extension method used to add the middleware to the HTTP request pipeline. public static class CustomExceptionMiddlewareExtensions { public static IApplicationBuilder UseCustomExceptionMiddleware(this IApplicationBuilder builder) { return builder.UseMiddleware<CustomExceptionMiddleware>(); } }

之后，我們只需要將其注入到應用程序的請求管道中即可：

Copy

public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { app.UseCustomExceptionMiddleware(); }

使用過濾器移除重復代碼#

USING ACTIONFILTERS TO REMOVE DUPLICATED CODE

ASP.NET Core 的過濾器可以讓我們在請求管道的特定狀態之前或之后運行一些代碼。因此如果我們的 action 中有重復驗證的話，可以使用它來簡化驗證操作。

當我們在 action 方法中處理 PUT 或者 POST 請求時，我們需要驗證我們的模型對象是否符合我們的預期。作為結果，這將導致我們的驗證代碼重復，我們希望避免出現這種情況，（基本上，我們應該盡我們所能避免出現任何代碼重復。）我們可以在代碼中通過使用 ActionFilter 來代替我們的驗證代碼：

Copy

if (!ModelState.IsValid) { //bad request and logging logic }

我們可以創建一個過濾器：

Copy

public class ModelValidationAttribute : ActionFilterAttribute { public override void OnActionExecuting(ActionExecutingContext context) { if (!context.ModelState.IsValid) { context.Result = new BadRequestObjectResult(context.ModelState); } } }

然后在 Startup 類的 ConfigureServices 函數中將其注入：

Copy

services.AddScoped<ModelValidationAttribute>();

現在，我們可以將上述注入的過濾器應用到我們的 action 中。

Microsoft.AspNetCore.All 元包#

MICROSOFT.ASPNETCORE.ALL META-PACKAGE

注：如果你使用的是 2.1 和更高版本的 ASP.NET Core。建議使用 Microsoft.AspNetCore.App 包，而不是 Microsoft.AspNetCore.All。這一切都是出於安全原因。此外，如果使用 2.1 版本創建新的 WebAPI 項目，我們將自動獲取 AspNetCore.App 包，而不是 AspNetCore.All。

這個元包包含了所有 AspNetCore 的相關包，EntityFrameworkCore 包，SignalR 包（version 2.1） 和依賴框架運行的支持包。采用這種方式創建一個新項目很方便，因為我們不需要手動安裝一些我們可能使用到的包。

當然，為了能使用 Microsoft.AspNetCore.all 元包，需要確保你的機器安裝了 .NET Core Runtime。

路由#

ROUTING

在 .NET Core Web API 項目中，我們應該使用屬性路由代替傳統路由，這是因為屬性路由可以幫助我們匹配路由參數名稱與 Action 內的實際參數方法。另一個原因是路由參數的描述，對我們而言，一個名為 "ownerId" 的參數要比 "id" 更加具有可讀性。

我們可以使用 [Route] 屬性來在控制器的頂部進行標注：

Copy

[Route("api/[controller]")] public class OwnerController : Controller { [Route("{id}")] [HttpGet] public IActionResult GetOwnerById(Guid id) { } }

還有另一種方式為控制器和操作創建路由規則：

Copy

[Route("api/owner")] public class OwnerController : Controller { [Route("{id}")] [HttpGet] public IActionResult GetOwnerById(Guid id) { } }

對於這兩種方式哪種會好一些存在分歧，但是我們經常建議采用第二種方式。這是我們一直在項目中采用的方式。

當我們談論路由時，我們需要提到路由的命名規則。我們可以為我們的操作使用描述性名稱，但對於 路由/節點，我們應該使用 NOUNS 而不是 VERBS。

一個較差的示例：

Copy

[Route("api/owner")] public class OwnerController : Controller { [HttpGet("getAllOwners")] public IActionResult GetAllOwners() { } [HttpGet("getOwnerById/{id}"] public IActionResult GetOwnerById(Guid id) { } }

一個較好的示例：

Copy

[Route("api/owner")] public class OwnerController : Controller { [HttpGet] public IActionResult GetAllOwners() { } [HttpGet("{id}"] public IActionResult GetOwnerById(Guid id) { } } 

更多關於 Restful 實踐的細節解釋，請查閱：Top REST API Best Practices

日志#

LOGGING

如果我們打算將我們的應用程序發布到生產環境，我們應該在合適的位置添加一個日志記錄機制。在生產環境中記錄日志對於我們梳理應用程序的運行很有幫助。

.NET Core 通過繼承 ILogger 接口實現了它自己的日志記錄。通過借助依賴注入機制，它可以很容易地使用。

Copy

public class TestController: Controller { private readonly ILogger _logger; public TestController(ILogger<TestController> logger) { _logger = logger; } }

然后，在我們的 action 中，我們可以通過使用 _logger 對象借助不同的日志級別來記錄日志。

.NET Core 支持使用於各種日志記錄的 Provider。因此，我們可能會在項目中使用不同的 Provider 來實現我們的日志邏輯。

NLog 是一個很不錯的可以用於我們自定義的日志邏輯類庫，它極具擴展性。支持結構化日志，且易於配置。我們可以將信息記錄到控制台，文件甚至是數據庫中。

想了解更多關於該類庫在 .NET Core 中的應用，請查閱：.NET Core series – Logging With NLog.

Serilog 也是一個很不錯的類庫，它適用於 .NET Core 內置的日志系統。

加密#

CRYPTOHELPER

我們不會建議將密碼以明文形式存儲到數據庫中。處於安全原因，我們需要對其進行哈希處理。這超出了本指南的內容范圍。互聯網上有大量哈希算法，其中不乏一些不錯的方法來將密碼進行哈希處理。

但是如果需要為 .NET Core 的應用程序提供易於使用的加密類庫，CryptoHelper 是一個不錯的選擇。

CryptoHelper 是適用於 .NET Core 的獨立密碼哈希庫，它是基於 PBKDF2 來實現的。通過創建 Data Protection 棧來將密碼進行哈希化。這個類庫在 NuGet 上是可用的，並且使用也很簡單：

Copy

using CryptoHelper; // Hash a password public string HashPassword(string password) { return Crypto.HashPassword(password); } // Verify the password hash against the given password public bool VerifyPassword(string hash, string password) { return Crypto.VerifyHashedPassword(hash, password); }

內容協商#

CONTENT NEGOTIATION

默認情況下，.NET Core Web API 會返回 JSON 格式的結果。大多數情況下，這是我們所希望的。

但是如果客戶希望我們的 Web API 返回其它的響應格式，例如 XML 格式呢？

為了解決這個問題，我們需要進行服務端配置，用於按需格式化我們的響應結果：

Copy

public void ConfigureServices(IServiceCollection services) { services.AddControllers().AddXmlSerializerFormatters(); }

但有時客戶端會請求一個我們 Web API 不支持的格式，因此最好的實踐方式是對於未經處理的請求格式統一返回 406 狀態碼。這種方式也同樣能在 ConfigureServices 方法中進行簡單配置：

Copy

public void ConfigureServices(IServiceCollection services) { services.AddControllers(options => options.ReturnHttpNotAcceptable = true).AddXmlSerializerFormatters(); }

我們也可以創建我們自己的格式化規則。

這一部分內容是一個很大的主題，如果你希望了解更對，請查閱：Content Negotiation in .NET Core

使用 JWT#

USING JWT

現如今的 Web 開發中，JSON Web Tokens (JWT) 變得越來越流行。得益於 .NET Core 內置了對 JWT 的支持，因此實現起來非常容易。JWT 是一個開發標准，它允許我們以 JSON 格式在服務端和客戶端進行安全的數據傳輸。

我們可以在 ConfigureServices 中配置 JWT 認證：

Copy

public void ConfigureServices(IServiceCollection services) { services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options => { options.TokenValidationParameters = new TokenValidationParameters { ValidateIssuer = true, ValidIssuer = _authToken.Issuer, ValidateAudience = true, ValidAudience = _authToken.Audience, ValidateIssuerSigningKey = true, IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_authToken.Key)), RequireExpirationTime = true, ValidateLifetime = true, //others }; }); }

為了能在應用程序中使用它，我們還需要在 Configure 中調用下面一段代碼：

Copy

public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { app.UseAuthentication(); }

此外，創建 Token 可以使用如下方式：

Copy

var securityToken = new JwtSecurityToken( claims: new Claim[] { new Claim(ClaimTypes.NameIdentifier,user.Id), new Claim(ClaimTypes.Email,user.Email) }, issuer: _authToken.Issuer, audience: _authToken.Audience, notBefore: DateTime.Now, expires: DateTime.Now.AddDays(_authToken.Expires), signingCredentials: new SigningCredentials( new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_authToken.Key)), SecurityAlgorithms.HmacSha256Signature)); Token = new JwtSecurityTokenHandler().WriteToken(securityToken)

基於 Token 的用戶驗證可以在控制器中使用如下方式：

Copy

var auth = await HttpContext.AuthenticateAsync(); var id = auth.Principal.Claims.FirstOrDefault(x => x.Type.Equals(ClaimTypes.NameIdentifier))?.Value;

我們也可以將 JWT 用於授權部分，只需添加角色聲明到 JWT 配置中即可。

更多關於 .NET Core 中 JWT 認證和授權部分，請查閱：authentication-aspnetcore-jwt-1 和 authentication-aspnetcore-jwt-2

總結#

讀到這里，可能會有朋友對上述一些最佳實踐不是很認同，因為全篇都沒有談及更切合項目的實踐指南，比如 TDD 、DDD 等。但我個人認為上述所有的最佳實踐是基礎，只有把這些基礎掌握了，才能更好地理解一些更高層次的實踐指南。萬丈高樓平地起，所以你可以把這看作是一篇面向新手的最佳實踐指南。

在這份指南中，我們的主要目的是讓你熟悉關於使用 .NET Core 開發 web API 項目時的一些最佳實踐。這里面的部分內容在其它框架中也同樣適用。因此，熟練掌握它們很有用。

非常感謝你能閱讀這份指南，希望它能對你有所幫助。