ASP.NET Core WebAPI 版本控制實現指南
作者：conan
ASP.NET Core WebAPI 提供了靈活且強大的版本控制功能，通過 Microsoft.AspNetCore.Mvc.Versioning 包，開發者可以輕松實現基于查詢字符串、URL路徑段和HTTP頭的版本控制。
在現代軟件開發中，API版本控制是一項至關重要的功能，它允許開發者在不破壞現有系統的情況下推出新功能，同時確保向后兼容性。ASP.NET Core WebAPI 提供了多種實現版本控制的方法，本文將詳細介紹如何使用 Microsoft.AspNetCore.Mvc.Versioning 包來實現這一功能。
一、前提條件
- Visual Studio：確保安裝了 Visual Studio 16.4 或更高版本。
- .NET Core：確保已安裝 .NET Core 3.1 或更高版本。
- Postman：用于測試 Web API（如果尚未安裝，可以從 Postman 官網下載）。
二、創建 ASP.NET Core Web API 項目
- 打開 Visual Studio，單擊“文件”->“新建”->“項目”。
- 選擇“ASP.NET Core Web 應用程序”模板，單擊“下一步”。
- 給項目命名，并單擊“創建”按鈕。
- 選擇“API”模板，單擊“創建”按鈕。
三、安裝 Microsoft.AspNetCore.Mvc.Versioning 包
- 右鍵單擊解決方案，選擇“管理 NuGet 包”。
- 搜索“Microsoft.AspNetCore.Mvc.Versioning”并安裝。
四、配置版本控制
- 打開 Startup.cs 文件，在 ConfigureServices 方法中添加以下代碼：
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddApiVersioning(options =>
{
// 返回響應標頭中支持的版本信息
options.ReportApiVersions = true;
// 默認情況下，假定未指定版本的請求為1.0版本
options.AssumeDefaultVersionWhenUnspecified = true;
// 設置默認API版本
options.DefaultApiVersion = new ApiVersion(1, 0);
// 支持MediaType、Header、QueryString設置版本號，默認使用QueryString
options.ApiVersionReader = ApiVersionReader.Combine(
new MediaTypeApiVersionReader("api-version"),
new HeaderApiVersionReader("api-version"),
new QueryStringApiVersionReader("api-version"),
new UrlSegmentApiVersionReader()
);
});
}- 在 Configure 方法中啟用版本控制：
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseHttpsRedirection();
app.UseApiVersioning();
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}五、實現版本控制
- 基于查詢字符串的版本控制使用 [ApiVersion] 屬性標記控制器或方法，并通過查詢字符串傳遞 api-version 參數。
[ApiController]
[Route("[controller]")]
[ApiVersion("1.0", Deprecated = true)]
[ApiVersion("2.0")]
public class WeatherForecastController : ControllerBase
{
// 控制器方法
}調用方式：https://localhost:5000/weatherforecast?api-version=1.0 或 https://localhost:5000/weatherforecast?api-version=2.0
- 基于URL路徑段的版本控制在控制器路由中添加版本段，例如 /api/v{version:apiVersion}/[controller]。
[ApiController]
[Route("/api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class WeatherForecastController : ControllerBase
{
// 控制器方法
}調用方式：https://localhost:5000/api/v1/weatherforecast 或 https://localhost:5000/api/v2/weatherforecast
- 基于HTTP頭的版本控制在請求頭中傳遞 api-version 參數。
options.ApiVersionReader = ApiVersionReader.Combine(
new MediaTypeApiVersionReader("api-version"),
new HeaderApiVersionReader("api-version")
);調用方式：在請求頭中添加 api-version: 1.0 或 api-version: 2.0
六、測試版本控制
使用 Postman 或其他 API 測試工具，通過不同的方式（查詢字符串、URL路徑段、HTTP頭）傳遞 api-version 參數，驗證版本控制是否生效。
七、總結
ASP.NET Core WebAPI 提供了靈活且強大的版本控制功能，通過 Microsoft.AspNetCore.Mvc.Versioning 包，開發者可以輕松實現基于查詢字符串、URL路徑段和HTTP頭的版本控制。這些功能不僅有助于及時推出新功能，還能確保現有系統的向后兼容性，為開發者提供了更多的靈活性和控制力。
責任編輯：武曉燕
來源：
程序員編程日記
