Ultimate ASP.NET CORE 6.0 Web API --- 读书笔记（24）

24 Versioning APIs

本文内容来自书籍： Marinko Spasojevic - Ultimate ASP.NET Core Web API - From Zero To Six-Figure Backend Developer (2nd edition)
需要本书和源码的小伙伴可以留下邮箱，有空看到会发送的

会破坏API的使用的情况

• 重命名字段，属性，或者资源的URI
• 修改负载的结构
• 修改响应码
• 重新设计API端点

在这些情况下，最好的做法是应用版本管理，这样可以防止已经被消费者使用的API

在ASP.NET Core 中做到版本管理，需要安装包Microsoft.AspNetCore.Mvc.Versioning在Presentation

1. 在主项目配置服务

public static void ConfigureVersioning(this IServiceCollection services)
{
    services.AddApiVersioning(opt =>
    {
        opt.ReportApiVersions = true;
        opt.AssumeDefaultVersionWhenUnspecified = true;
        opt.DefaultApiVersion = new ApiVersion(1, 0);
    });
}

• ReportApiVersions：添加API的版本到响应头中
• AssumeDefaultVersionWhenUnspecified：如果客户端的请求没有带有版本，这个会添加一个默认
• DefaultApiVersion：默认版本

2. 在控制器中添加版本

// 代表新添加的API，原有的相同路由的控制器是1.0
[ApiVersion("2.0")]
[ApiController]
[Route("api/companies")]
public class CompaniesV2Controller : ControllerBase
{
    private readonly IServiceManager _service;
    public CompaniesV2Controller(IServiceManager service) => _service = service;
    
    [HttpGet]
    public async Task<IActionResult> GetCompanies()
    {
        var companies = await _service.CompanyService.GetAllCompaniesAsync(trackChanges: false);
        return Ok(companies);
    }
}

3. 在请求的查询参数中添加需要的版本

添加配置

    opt.ApiVersionReader = new QueryStringApiVersionReader("api-version");

https://localhost:5001/api/companies?api-version=2.0

然后在响应头中会出现api-supported-versions: 2.0

4. 也可以直接在URI中添加版本

[ApiVersion("2.0")]
[ApiController]
[Route("api/{v:apiversion}/companies")]

然后在请求的时候，https://localhost:5001/api/2.0/companies，带上版本，就可以返回相应的内容

5. 请求头中带有版本

public static void ConfigureVersioning(this IServiceCollection services)
{
    services.AddApiVersioning(opt =>
    {
        opt.ReportApiVersions = true;
        opt.AssumeDefaultVersionWhenUnspecified = true;
        opt.DefaultApiVersion = new ApiVersion(1, 0);
        opt.ApiVersionReader = new HeaderApiVersionReader("api-version");
    });
}

然后客户端在请求头中只需要添加这个头，就可以使用了，而不需要更改URI

6. 抛弃某个API版本，但是没有马上删除这个API

在需要删除的API中添加信息

[ApiVersion("2.0", Deprecated = true)]

然后在响应头api-deprecated-versions: 2.0中会有相关提示信息，说明这个API已经被抛弃了

7. 如果一个API有很多版本，可以在配置中配置

services.AddApiVersioning(opt =>
{
    opt.ReportApiVersions = true;
    opt.AssumeDefaultVersionWhenUnspecified = true;
    opt.DefaultApiVersion = new ApiVersion(1, 0);
    opt.ApiVersionReader = new HeaderApiVersionReader("api-version");
    opt.Conventions.Controller<CompaniesController>()
            .HasApiVersion(new ApiVersion(1, 0));
    opt.Conventions.Controller<CompaniesV2Controller>()
            .HasDeprecatedApiVersion(new ApiVersion(2, 0));
});

然后控制器上的[ApiVersion]就可以去除了