面试题：C#的API设计中如何处理版本控制与RESTful服务的兼容性

常见版本控制策略

URL版本控制
- 实现方式：在URL路径中包含版本号，例如 /api/v1/users，/api/v2/users。
- 优点：简单直观，客户端和服务器端都容易理解和实现；对旧版本的兼容性好，旧版本的客户端仍然可以使用旧的URL进行访问。
- 缺点：版本号与资源紧密耦合，可能导致URL冗长；如果需要对版本号进行更改，可能需要对所有相关的URL进行修改。
Header版本控制
- 实现方式：在HTTP请求头中添加自定义的版本号字段，例如 Accept - API - Version: v1 或 X - API - Version: v1。
- 优点：URL保持简洁，不会因为版本号而变得冗长；可以在不改变URL的情况下灵活切换版本，方便对API进行演进。
- 缺点：客户端需要额外配置请求头，增加了客户端的复杂度；对于一些不支持自定义请求头的客户端（如某些旧浏览器）可能不太友好；文档说明相对复杂，需要明确告知客户端如何设置请求头。
媒体类型（Content - Type）版本控制
- 实现方式：通过在 Content - Type 或 Accept 头中指定版本相关的媒体类型，例如 application/vnd.company.product.v1+json，application/vnd.company.product.v2+json。
- 优点：符合HTTP协议中关于媒体类型的规范；可以很好地与缓存机制协同工作，不同版本的资源可以作为不同的媒体类型进行缓存；对于支持媒体类型协商的客户端和服务器端来说，这种方式比较自然。
- 缺点：同样增加了客户端的复杂度，需要正确设置 Content - Type 或 Accept 头；媒体类型的定义和维护需要一定的规范和管理，否则可能会出现混乱。

在ASP.NET Core项目中的具体实现

路由

URL版本控制：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Routing;

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "v1",
            pattern: "api/v1/{controller}/{action}/{id?}");
        endpoints.MapControllerRoute(
            name: "v2",
            pattern: "api/v2/{controller}/{action}/{id?}");
    });
}

Header版本控制：可以通过自定义中间件来解析请求头中的版本号，并根据版本号选择不同的路由配置。例如：

public class ApiVersionHeaderMiddleware
{
    private readonly RequestDelegate _next;

    public ApiVersionHeaderMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task Invoke(HttpContext context)
    {
        var apiVersion = context.Request.Headers["X - API - Version"].FirstOrDefault();
        if (!string.IsNullOrEmpty(apiVersion))
        {
            // 根据apiVersion调整路由逻辑
        }
        await _next(context);
    }
}

public static class ApiVersionHeaderMiddlewareExtensions
{
    public static IApplicationBuilder UseApiVersionHeader(this IApplicationBuilder builder)
    {
        return builder.UseMiddleware<ApiVersionHeaderMiddleware>();
    }
}

媒体类型版本控制：在ASP.NET Core中，可以通过自定义 OutputFormatter 和 InputFormatter 来处理不同版本的媒体类型。例如：

public class V1ProductOutputFormatter : TextOutputFormatter
{
    public V1ProductOutputFormatter()
    {
        SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("application/vnd.company.product.v1+json"));
        SupportedEncodings.Add(Encoding.UTF8);
        SupportedEncodings.Add(Encoding.Unicode);
    }

    protected override bool CanWriteType(Type type)
    {
        return typeof(Product).IsAssignableFrom(type);
    }

    public override async Task WriteResponseBodyAsync(OutputFormatterWriteContext context, Encoding selectedEncoding)
    {
        var response = context.HttpContext.Response;
        var products = context.Object as IEnumerable<Product>;
        // 处理v1版本的输出逻辑
        await response.WriteAsync("V1 product output");
    }
}

然后在 Startup.cs 中注册：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options =>
    {
        options.OutputFormatters.Add(new V1ProductOutputFormatter());
    });
}

控制器

URL版本控制：不同版本的控制器可以放在不同的命名空间或者文件夹下，通过路由映射到不同版本的URL。例如：

namespace MyProject.Controllers.V1
{
    [Route("api/v1/[controller]")]
    [ApiController]
    public class UsersController : ControllerBase
    {
        [HttpGet]
        public IActionResult Get()
        {
            // v1版本获取用户逻辑
            return Ok("V1 users");
        }
    }
}

namespace MyProject.Controllers.V2
{
    [Route("api/v2/[controller]")]
    [ApiController]
    public class UsersController : ControllerBase
    {
        [HttpGet]
        public IActionResult Get()
        {
            // v2版本获取用户逻辑
            return Ok("V2 users");
        }
    }
}

Header版本控制：在控制器中可以通过依赖注入获取当前请求的上下文，从而读取请求头中的版本号，根据版本号执行不同的业务逻辑。例如：

[ApiController]
[Route("[controller]")]
public class UsersController : ControllerBase
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public UsersController(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    [HttpGet]
    public IActionResult Get()
    {
        var apiVersion = _httpContextAccessor.HttpContext.Request.Headers["X - API - Version"].FirstOrDefault();
        if (apiVersion == "v1")
        {
            // v1版本逻辑
            return Ok("V1 users");
        }
        else if (apiVersion == "v2")
        {
            // v2版本逻辑
            return Ok("V2 users");
        }
        return BadRequest("Unsupported API version");
    }
}

媒体类型版本控制：控制器根据请求的媒体类型来决定执行哪个版本的业务逻辑。例如：

[ApiController]
[Route("[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        var acceptHeader = Request.Headers["Accept"].FirstOrDefault();
        if (acceptHeader.Contains("application/vnd.company.product.v1+json"))
        {
            // v1版本逻辑
            return Ok("V1 products");
        }
        else if (acceptHeader.Contains("application/vnd.company.product.v2+json"))
        {
            // v2版本逻辑
            return Ok("V2 products");
        }
        return BadRequest("Unsupported media type version");
    }
}

文档说明
- URL版本控制：在API文档中明确列出不同版本的URL结构，例如Swagger文档中可以通过分组来展示不同版本的API，每个分组对应一个版本的URL前缀。
- Header版本控制：在文档中详细说明需要在请求头中设置的版本号字段，以及不同版本对应的功能变化和请求示例。
- 媒体类型版本控制：文档中要清晰描述每个版本对应的媒体类型，以及如何在请求中设置正确的 Content - Type 或 Accept 头来访问特定版本的API，同时给出不同版本媒体类型下的数据结构示例。

星途面试题库

面试题：C#的API设计中如何处理版本控制与RESTful服务的兼容性

知识考点

面试题答案

常见版本控制策略

在ASP.NET Core项目中的具体实现