原文地址： 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 服務的不好方式：

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

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

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

一種好的方式是通過在擴充套件類中建立靜態方法：

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

然後，只需要呼叫這個擴充套件方法即可：

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 內建功能。通過這種方式，我們可以在任何控制器中通過建構函式注入的方式來使用。

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

控制器

CONTROLLERS

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

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

public class OwnerController : Controller
{
    private ILoggerManager _logger;
    private 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 請求，驗證模型，捕捉異常和返回響應。

[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 方法：

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

我們也可以通過建立自定義的中介軟體來實現我們的自定義異常處理：

// 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>();
    }
}

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

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

使用過濾器移除重複程式碼

USING ACTIONFILTERS TO REMOVE DUPLICATED CODE

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

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

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

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

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

然後在 Startup 類的 ConfigureServices 函式中將其注入：

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] 屬性來在控制器的頂部進行標註：

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

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

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

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

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

一個較差的示例：

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

一個較好的示例：

[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 介面實現了它自己的日誌記錄。通過藉助依賴注入機制，它可以很容易地使用。

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 上是可用的，並且使用也很簡單：

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 格式呢？

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

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

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

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 認證：

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 中呼叫下面一段程式碼：

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

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

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 的使用者驗證可以在控制器中使用如下方式：

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 專案時的一些最佳實踐。這裡面的部分內容在其它框架中也同樣適用。因此，熟練掌握它們很有用。

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