《ASP.NET Core 与 RESTful API 开发实战》-- （第7章）-- 读书笔记（中）

第 7 章高级主题

7.2 并发

当两个用户获取同一个资源后，再同时修改该资源，就会导致并发问题

常见实现并发的方法有以下两种：

保守式并发控制，每次修改资源，都锁定资源
开放式并发控制，每次修改资源，将获取资源时得到的资源散列值一并提交给服务器，判断是否有效，有效则意味着资源未被修改

由于 HTTP 无状态，对于 RESTful API 应用程序来说，只能使用开放式并发控制，可以使用上一节提到的 ETag 来实现

接下来为图书资源更新与部分更新实现并发控制

对于 PUT 或 PATCH 请求，必须检查客户端的请求消息头是否包含 If-Match 消息头，可以通过过滤器判断

namespace Library.API.Filters
{
    public class CheckIfMatchHeaderFilterAttribute : ActionFilterAttribute
    {
        public override Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
        {
            if (!context.HttpContext.Request.Headers.ContainsKey(HeaderNames.IfMatch))
            {
                context.Result = new BadRequestObjectResult(new ApiError
                {
                    Message = "必须提供 If-Match 消息头"
                });
            }

            return base.OnActionExecutionAsync(context, next);
        }
    }
}

接着在 BookController 的 UpdateBookAsync 和 PartiallyUpdateBookAsync 两个方法应用该特性

[HttpPut("{bookId}")]
[CheckIfMatchHeaderFilter]
public async Task<IActionResult> UpdateBookAsync(Guid authorId, Guid bookId, BookForUpdateDto updateBook)
{
    var book = await RepositoryWrapper.Book.GetBookAsync(authorId, bookId);
    if (book == null)
    {
        return NotFound();
    }

    // 资源已被修改，返回412
    var entityHash = HashFactory.GetHash(book);
    if (Request.Headers.TryGetValue(HeaderNames.IfMatch, out var requestETag) && requestETag != entityHash)
    {
        return StatusCode(StatusCodes.Status412PreconditionFailed);
    }

    Mapper.Map(updateBook, book, typeof(BookForUpdateDto), typeof(Book));
    RepositoryWrapper.Book.Update(book);
    if (!await RepositoryWrapper.Book.SaveAsync())
    {
        throw new Exception("更新资源 Book 失败");
    }

    // 资源未被修改，更新散列值
    var entityNewHash = HashFactory.GetHash(book);
    Response.Headers[HeaderNames.ETag] = entityNewHash;

    return NoContent();
}

PartiallyUpdateBookAsync 逻辑同上

7.3 版本

指定版本的方法有两种：

使用 [ApiVersion] 特性
使用版本约定特性

ASP.NET Core MVC 默认的方式是使用查询字符串，参数名为 api-version

添加nuget

Install-Package Microsoft.AspNetCore.Mvc.Versioning

然后添加 API 版本服务，在 ConfigureServices 中

services.AddApiVersioning(options =>
{
    // 指明当客户端未提供版本时是否使用默认版本，默认为false
    options.AssumeDefaultVersionWhenUnspecified = true;
    // 指明了默认版本
    options.DefaultApiVersion = new ApiVersion(1, 0);
    // 指明是否在HTTP响应消息头中包含api-supported-versions和api-deprecated-versions这两项
    options.ReportApiVersions = true;
});

接下来，添加一个 PersonController

using Microsoft.AspNetCore.Mvc;

namespace Library.API.Controllers.V1
{
    [Microsoft.AspNetCore.Components.Route("api/person")]
    [ApiVersion("1.0")]
    public class PersonController : ControllerBase
    {
        [HttpGet]
        public ActionResult<string> Get() => "Result from v1";
    }
}

namespace Library.API.Controllers.V2
{
    [Microsoft.AspNetCore.Components.Route("api/person")]
    [ApiVersion("2.0")]
    public class PersonController : ControllerBase
    {
        [HttpGet]
        public ActionResult<string> Get() => "Result from v2";
    }
}

运行程序，访问 http://localhost:5001/api/person

结果返回 Result from v1，因为默认版本1.0

访问 http://localhost:5001/api/person?api-version=2.0

结果返回 Result from v2

参数名 api-version 可改为自定义参数名，通过 ApiVersionReader 设置

options.ApiVersionReader = new QueryStringApiVersionReader("ver");

使用 URL 路径形式来访问指定版本 API，需要为 Controller 修改路由

[Route("api/v{version:apiVersion}/students")]

运行程序，访问 http://localhost:5001/api/v2/students

即可访问相应的版本接口

使用自定义 HTTP 消息头访问指定 API

options.ApiVersionReader = new HeaderApiVersionReader("api-version");

在消息头添加 api-version 项

还可以通过媒体类型来获取 API

options.ApiVersionReader = new MediaTypeApiVersionReader();

在请求消息头添加 Content-Type，它的值为 application/json;v=2

如果要同时支持多种方式，则可以使用 Combine

options.ApiVersionReader = ApiVersionReader.Combine(
                    new MediaTypeApiVersionReader(),
                    new QueryStringApiVersionReader("api-version"));

除了 Controller 级别的版本外，还可以创建 Action 级别的版本

namespace Library.API.Controllers
{
    [Route("api/news")]
    [ApiVersion("1.0")]
    [ApiVersion("2.0")]
    public class NewController : ControllerBase
    {
        [HttpGet]
        public ActionResult<string> Get() => "Result from v1";

        [HttpGet, MapToApiVersion("2.0")]
        public ActionResult<string> GetV2() => "Result from v2";
    }
}

先前的版本不需要时，可以将 Deprecated 属性设置为 true

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

除了特性外，ASP.NET Core MVC 还支持使用约定的方式来指定

options.Conventions.Controller<Controllers.V1.PersonController>()
                    .HasApiVersion(new ApiVersion(1,0));

相比特性，这种方式的优点是能够集中地管理应用程序所有 API 的版本信息，还可以灵活、动态地为 API 配置版本

在程序中获取客户端请求版本信息

protected ApiVersion RequestApiVersion => HttpContext.GetRequestedApiVersion();

本作品采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议进行许可。

欢迎转载、使用、重新发布，但务必保留文章署名郑子铭（包含链接： http://www.cnblogs.com/MingsonZheng/ ），不得用于商业目的，基于本文修改后的作品务必以相同的许可发布。

如有任何疑问，请与我联系 (MingsonZheng@outlook.com) 。