asp.net web api的版本管理是通过微软的一个包来实现的。
Install-Package Microsoft.AspNetCore.Mvc.Versioning
通过url参数: api/order/api-version=2.0
在startup中注入ApiVersion
public void ConfigureServices(IServiceCollection services)
{
services.AddApiVersioning();
services.AddControllers();
}
在ProductController中标注版本特性
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
namespace APIVersionDemo.Controllers
{
[ApiController]
[Route("api/[controller]")]
[ApiVersion("1.0", Deprecated = true)]
[ApiVersion("2.0")]
public class ProductController : ControllerBase
{
private readonly ILogger<ProductController> _logger;
public ProductController(ILogger<ProductController> logger)
{
_logger = logger;
}
//1.0的api
[HttpGet("{id}")]
public Product QueryProduct([FromRoute] int id)
{
_logger.LogInformation("v1.0查询产品");
return new Product() { ID = id, Name = "A物品", Price = 100.20m };
}
//2.0的api
[HttpGet("{id}")]
[MapToApiVersion("2.0")]
public Product QueryProductv2([FromRoute] int id)
{
_logger.LogInformation("v2.0查询产品");
return new Product2() { ID = id, Name = "A物品", Price = 100.20m, Description = "产自山西" };
}
}
/// <summary>
/// 1.0的产品类
/// </summary>
public class Product
{
public int ID { get; set; }
public string Name { get; set; }
public decimal Price { get; set; }
}
/// <summary>
/// 2.0的产品类
/// </summary>
public class Product2 : Product
{
public string Description { get; set; }
}
}
通过http://localhost:5000/api/product/1?api-version=2.0方式访问不同的版本。显而易见,这种通过在请求url末尾加参数的方式有点啰嗦。
通过MediaType:{Accept:application/json;version=2.0}或header:{version:2.0}
修改startup的apiversion注入参数
public void ConfigureServices(IServiceCollection services)
{
services.AddApiVersioning(opt =>
{
opt.AssumeDefaultVersionWhenUnspecified = true;
opt.DefaultApiVersion = new ApiVersion(1, 0);
opt.ApiVersionReader = ApiVersionReader.Combine(
new MediaTypeApiVersionReader("version"),
new HeaderApiVersionReader("api-version")
);
opt.ReportApiVersions = true;
});
services.AddControllers();
}
ProductController不变。
请求http://localhost:5000/api/product/1,header参数,可以适配两种方式:
Accept : application/json;version=2.0
api-version : 2.0
这样方便客户端请求的整体处理。
通过url:api/v2.0/order
strartup.cs注入apiversion
public void ConfigureServices(IServiceCollection services)
{
services.AddApiVersioning();
services.AddControllers();
}
这里引入OrderController,在Route特性上改变url,在url里增加版本信息{version:apiVersion}
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.ApplicationModels;
using Microsoft.Extensions.Logging;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
namespace APIVersionDemo.Controllers
{
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0", Deprecated = true)]
[ApiVersion("2.0")]
public class OrderController : ControllerBase
{
private readonly ILogger<OrderController> _logger;
public OrderController(ILogger<OrderController> logger)
{
_logger = logger;
}
//v1订单api
[HttpGet("{id}")]
public Order QueryOrder()
{
_logger.LogInformation("v1查询产品");
return new Order()
{
OrderID = 1,
Products = new List<Product>()
{
new Product() { ID = 1, Name = "A物品", Price = 100.20m }
}
};
}
//v2订单api
[HttpGet("{id}")]
[MapToApiVersion("2.0")]
public Order2 QueryOrder2()
{
_logger.LogInformation("v2查询产品");
return new Order2()
{
OrderID = 1,
Products = new List<Product2>()
{
new Product2() { ID = 1, Name = "A物品", Price = 100.20m, Description = "产自山西" }
}
};
}
}
//v1订单类
public class Order
{
public int OrderID { get; set; }
public List<Product> Products { get; set; }
}
//v2订单类
public class Order2
{
public int OrderID { get; set; }
public List<Product2> Products { get; set; }
}
}
这时请求就变成http://localhost:5000/api/v2.0/order了,可以通过不同的url来访问不同的api版本,这种方式也有利于客户端统一配置baseurl,来切换请求api版本。
最后,apiversion这个包还带来了一个无侵入controller的方式来配置api的版本,本质与加在Controller上的特性信息是一致的——附加版本信息和对应关系。
services.AddApiVersioning(opt =>
{
opt.Conventions.Controller<ProductController>()
.HasApiVersion(2, 0)
.HasDeprecatedApiVersion(1, 0)
.Action(typeof(ProductController)
.GetMethod(nameof(ProductController.QueryProductv2))!)
.MapToApiVersion(2, 0);
});