在 .NET Core 中构建 REST API

翻译自 Camilo Reyes 2020年8月26日的文章《Build a REST API in .NET Core》 ^[1]
REST API 可以使用简单的动词（如 POST、PUT、PATCH 等）将大型解决方案背后的复杂性隐藏起来。在本文中，Camilo Reyes 解释了如何在 .NET Core 中创建 REST API。

扩展大型复杂解决方案的一种方法是将它们分解为 REST 微服务。微服务开启了 API 背后的业务逻辑的可测试性和可重用性。因为 REST API 可以被多个客户端重用，使得组织可以共享软件模块。客户端或许是移动端、网页端，甚至单页应用中的静态资源端，它们可以调用任意多的 API。

在本文中，我将向您展示在 .NET Core 中构建 REST API 的全过程。我将用现实工作中的需求来解释这个过程，比如版本控制、搜索、日志记录等等。REST 通常与诸如 POST、PUT 或 PATCH 的动词一起使用，因此我打算将它们全部覆盖。我希望您看到的是，使用现有工具交付价值的一个好的有效的方式。

入门介绍

本文假定您已掌握了 ASP.NET、C# 和 REST API，因此我不会涉及任何基础知识。我建议在学习本文时使用最新的 .NET Core 版本^[2]。如果您想从工作代码开始学习，可以从 GitHub 下载^[3]示例代码。

你可以先新建一个文件夹，比如 BuildRestApiNetCore，然后在 shell 中打开它：

dotnet new sln
dotnet new webapi --no-https
dotnet sln add .

该项目基于禁用了 HTTPS 的 Web API 模板，以简化本地开发。双击解决方案文件会在 Visual Studio 中打开它（如果已安装）。为了支持 .NET Core 3.1，请确保安装了 2019 版的 IDE。

由于 API 在客户端和数据库之间建立了一层分离，因此准备数据是一个很好的开始。为了简化数据访问，Entity Framework 提供了一个内存中的替代方案，这样我就可以只关注 API 本身。

通过 NuGet 获取内存数据库提供程序：

dotnet add package Microsoft.EntityFrameworkCore.InMemory

然后，创建以下数据模型。我将其放在 Models 文件夹中，以表示此命名空间存放原始数据。若要使用数据标注，请在 using 语句中添加 System.ComponentModel.DataAnnotations。

public class Product
{[Key][Required][Display(Name = "productNumber")]public string ProductNumber { get; set; }[Required][Display(Name = "name")]public string Name { get; set; }[Required][Range(10, 90)][Display(Name = "price")]public double? Price { get; set; }[Required][Display(Name = "department")]public string Department { get; set; }
}

在实际的解决方案中，这可能要根据团队的需要将其放在单独的项目中。请注意分配给该模型的属性，例如 Required、Display 和 Range，这些是 ASP.NET 中的数据标注，用于在模型绑定时验证 Product。因为我使用的是内存数据库，所以 Entity Framework 需要一个唯一的 Key。这些属性指定了验证规则，例如：价格区间或者该属性是否是必须的。

从业务的视角来看，这是一个包含产品编号、名称和价格的电子商务站点。每个产品还指定了一个部门，以便按部门进行搜索。

接下来，在 Models 命名空间中设置 Entity Framework DbContext：

public class ProductContext : DbContext
{public ProductContext(DbContextOptions<ProductContext> options) : base(options){}public DbSet<Product> Products { get; set; }
}

该数据库上下文被依赖注入到控制器中，用于查询或更新数据。要在 ASP.NET Core 中启用依赖注入，请打开 Startup 类并将其添加到 ConfigureServices 中：

services.AddDbContext<ProductContext>(opt => opt.UseInMemoryDatabase("Products"));

这行代码完成了内存数据库。请确保在两个类的 using 语句中添加 Microsoft.EntityFrameworkCore。一个空白的后端是无趣的，因此我们来填充一些种子数据。

创建下面的扩展方法以帮助迭代生成种子数据，可以将它放在 Extensions 命名空间或文件夹中：

public static class EnumerableExtensions
{public static IEnumerable<T> Times<T>(this int count, Func<int, T> func){for (var i = 1; i <= count; i++) yield return func.Invoke(i);}
}

在 Models 命名空间下添加一个静态类以初始化种子数据：

public static class ProductSeed
{public static void InitData(ProductContext context){var rnd = new Random();var adjectives = new[] { "Small", "Ergonomic", "Rustic", "Smart", "Sleek" };var materials = new[] { "Steel", "Wooden", "Concrete", "Plastic", "Granite", "Rubber" };var names = new[] { "Chair", "Car", "Computer", "Pants", "Shoes" };var departments = new[] { "Books", "Movies", "Music", "Games", "Electronics" };context.Products.AddRange(900.Times(x =>{var adjective = adjectives[rnd.Next(0, 5)];var material = materials[rnd.Next(0, 5)];var name = names[rnd.Next(0, 5)];var department = departments[rnd.Next(0, 5)];var productId = $"{x,-3:000}";return new Product{ProductNumber = $"{department.First()}{name.First()}{productId}",Name = $"{adjective} {material} {name}",Price = (double)rnd.Next(1000, 9000) / 100,Department = department};}));context.SaveChanges();}
}

这段代码循环遍历一个 900 条数据的列表以生成大量的产品，这些产品的部门、价格和名称都是随机捡选的。每个产品都有一个“巧妙”的 key 作为主键，该主键由部门、名称和产品 Id 组合而成。

有了这些种子数据，您就可以得到诸如在 Electronics 部门带有标价的名为 “Smart Wooden Pants” 的产品了。

作为开始构建 Endpoints^[4]的第一步，设置 API 版本是一个好主意。这使得客户端应用可以随时升级 API 功能，而无需紧密耦合。

API 版本控制来自一个 NuGet 包：

dotnet add package Microsoft.AspNetCore.Mvc.Versioning

回到 Startup 类，并将其添加到 ConfigureServices 中：

services.AddApiVersioning(opt => opt.ReportApiVersions = true);

我选择在 API 响应中包含可用的版本号，以便客户端知道何时有升级可用。我推荐使用语义化的版本控制 ^[5]来传达 API 中的重大更改。让客户端知道每次升级都修改了什么，这样有助于每个客户端保持最新的功能。

REST API 中的搜索 Endpoint

要构建一个 Endpoint，请在 Controllers 文件夹中转到 ASP.NET 中的 Controller。

使用下面的代码创建一个 ProductsController，请确保在 using 语句中添加 Microsoft.AspNetCore.Mvc 命名空间：

[ApiController]
[ApiVersion("1.0")]
[Route("v{version:apiVersion}/[controller]")]
[Produces("application/json")]
public class ProductsController : ControllerBase
{private readonly ProductContext _context;public ProductsController(ProductContext context){_context = context;if (_context.Products.Any()) return;ProductSeed.InitData(context);}
}

请注意，当数据库中没有任何产品时，将运行 InitData 初始化种子数据。我设置了一个带有版本控制的 Route，版本号通过 ApiVersion 设置。通过依赖注入将数据上下文 ProductContext 注入到构造函数中。在该 Controller 中，第一个 Endpoint 是返回一个产品列表的 GET：

[HttpGet]
[Route("")]
[ProducesResponseType(StatusCodes.Status200OK)]
public ActionResult<IQueryable<Product>> GetProducts()
{var result = _context.Products as IQueryable<Product>;return Ok(result.OrderBy(p => p.ProductNumber));
}

请确保在 using 语句中添加 Microsoft.AspNetCore.Http，以设置响应类型中的状态码。

我选择按照产品编号排序产品，以便更简单地显示结果。在生产系统中，可以检查这种排序是否与聚集索引相匹配，以便减轻数据库的运行压力。经常检查执行计划和统计 IO，以确认有良好的性能。

此项目已经可以进行测试了！在命令行中运行以下命令：

dotnet watch run

使用 curl 测试该 Endpoint：

curl -i -X GET "http://localhost:5000/v1/products" -H "accept: application/json"

我在两个独立的控制台窗口中运行上面这两条命令。一个以监视模式运行项目，当我更改代码文件时，会自动重新生成并刷新；另一个是我保持 curl 结果的地方。您可以使用 Postman，但是伴随 Windows 10 而来的 curl 也可以完成该工作。

结果如下：

该请求返回数据库中的所有产品，但它不可扩展。随着产品列表的增加，客户端将受到未过滤数据的猛烈冲击，从而给 SQL 和网络流量带来更大的压力。

更好的方法是在一个模型中引入 limit 和 offset 请求参数：

public class ProductRequest
{[FromQuery(Name = "limit")]public int Limit { get; set; } = 15;[FromQuery(Name = "offset")]public int Offset { get; set; }
}

将此请求参数关联到 GetProducts Endpoint：

public ActionResult<IQueryable<Product>> GetProducts([FromQuery] ProductRequest request)
{var result = _context.Products as IQueryable<Product>;Response.Headers["x-total-count"] = result.Count().ToString();return Ok(result.OrderBy(p => p.ProductNumber).Skip(request.Offset).Take(request.Limit));
}

请注意我设置了一个值为 Count 的 HTTP header x-total-count，用于帮助想要分页浏览整个结果集的客户端。如果未指定请求参数，则该 API 默认返回前 15 条数据。

接下来，添加一个搜索参数，按部门筛选产品：

public ActionResult<IQueryable<Product>> GetProducts([FromQuery] string department, [FromQuery] ProductRequest request)
{// ...if (!string.IsNullOrEmpty(department)){result = result.Where(p => p.Department.StartsWith(department, StringComparison.InvariantCultureIgnoreCase));}// ..
}

可以通过修改 Query，让搜索进入条件块内。请注意我用了 StartsWith 和 InvariantCultureIgnoreCase 来简化产品过滤，在实际的 SQL 中，可以使用 LIKE 运算符，还可以通过排序规则设置不区分大小写。

要测试分页和此新过滤器，请使用 curl 执行以下命令：

curl -i -X GET "http://localhost:5000/v1/products?offset=15&department=electronics" -H "accept: application/json"

检查确定包含总数和受支持版本号的 HTTP 头：

HTTP/1.1 200 OK
Date: Thu, 28 Jan 2021 11:19:09 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Transfer-Encoding: chunked
x-total-count: 155
api-supported-versions: 1.0

日志记录和 API 文档

当 API 成形后，如何向其他开发人员传达 Endpoints 呢？对于团队来说，在不破坏开放代码的情况下了解 API 公开的内容是有好处的。Swagger 是这里的首选工具，它能通过反射，自动生成可用的文档。

如果我告诉您，Swagger 所需的一切都已经在此 API 中设置过了呢？来吧，再看一眼：

[Produces("application/json")]
[ProducesResponseType(StatusCodes.Status200OK)]
ActionResult<IQueryable<Product>> GetProducts([FromQuery] string department, [FromQuery] ProductRequest request)

ASP.NET 属性对于 Endpoints 的自文档化非常有用。Swagger 通过反射，从控制器方法中获得返回类型，进而推断响应该是什么样子，并获得每个控制器方法的请求参数。因为它收集了工作代码中的所有内容，所以可以生成“活文档”，从而减少了故障的发生。

通过 NuGet 获取缺少的依赖项：

dotnet add package Swashbuckle.AspNetCore

并在 ConfigureServices 中将其关联进来：

services.AddSwaggerGen(c => c.SwaggerDoc("v1", new OpenApiInfo
{Title = "Products",Description = "The ultimate e-commerce store for all your needs",Version = "v1"
}));

然后，在 Configure 中启用它：

app.UseSwagger();
app.UseSwaggerUI(opt => opt.SwaggerEndpoint("/swagger/v1/swagger.json", "Products v1"));

注意 OpenApiInfo 来自 Microsoft.OpenApi.Models 命名空间。

此时，在浏览器中导航到 http://localhost:5000/swagger 就可以查看 swagger 文档了。

页面大概如下显示：

在 swagger 文档中，您可以轻松浏览 API 并通过这个工具向 API 发起请求，您所在组织的其他开发人员会因此受益而轻松愉快，他们甚至可能会请您喝杯咖啡。

展开 GET /Products 查看从控制器方法中提取的 C# 数据类型：

下一站是日志记录。我将使用 NLog 在后端存储日志，使得 API 能够保存日志以供进一步分析。在实际环境中，日志对于故障排除非常有用；另外，它们还可以帮助收集遥测数据，以帮助了解 API 在未知状态下的使用情况。

要设置日志记录器，需要完成做以下操作：

一个 NuGet 包
一个 nlog.config 设置文件
修改 Program 类
微调 appsettings.json

安装 NuGet 包：

dotnet add package NLog.Web.AspNetCore

设置的 nlog.config 文件可以如下：

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"throwExceptions="false"throwConfigExceptions="false"autoReload="true"internalLogLevel="Warn"internalLogFile="C:\temp\BuildRestApiNetCore\RestApi-internal-nlog.txt"><extensions><add assembly="NLog.Web.AspNetCore"/></extensions><targets async="true"><target xsi:type="File"name="ownFile-web"fileName="C:\temp\BuildRestApiNetCore\RestApi-${shortdate}.log"><layout xsi:type="JsonLayout"><attribute name="Timestamp" layout="${longdate}" /><attribute name="Level" layout="${uppercase:${level}}" /><attribute name="Logger" layout="${logger}" /><attribute name="Action" layout="${aspnet-mvc-action}" /><attribute name="Message" layout="${message}" /><attribute name="Exception" layout="${exception:format=tostring}" /></layout></target></targets><rules><logger name="Microsoft.*" maxlevel="Info" final="true" /> <logger name="*" minlevel="Info" writeTo="ownFile-web" /></rules>
</nlog>

请注意 Layout，因为它设置了日志文件的类型，这里将其设置为 JsonLayout。当在不同的分析工具中使用日志文件时，JSON 格式具有最大的灵活性。为了让冗余降到最小，记录器规则不记录来自 Microsoft.* 的错误。另外，因为将 throwExceptions 设置为了 false，API 中未处理的异常会被记录，但不会被重新抛出。这里的用法可能是多变的，但通常最好是在 logger 中处理所有未处理的异常。

在 Program 类中，启用 NLog，记得添加 using NLog.Web：

Host.CreateDefaultBuilder(args).ConfigureWebHostDefaults(webBuilder =>{webBuilder.UseStartup<Startup>();}).UseNLog();

最后，在 appsettings.json 中进行以下微调来配置日志记录：

"Logging": {"LogLevel": {"Default": "Information","Microsoft": "None","Microsoft.AspNetCore": "Error","Microsoft.Hosting.Lifetime": "Information"}
}

这里的基本思想是减少与此 API 无关的日志条目的数量。您可以随意调整这些设置，以便恰当地记录 API 所需要的日志内容。

是时候言归正传了，在 Controller 类中，添加 using Microsoft.Extensions.Logging 并注入一个普通的旧式 ASP.NET logger：

private readonly ILogger<ProductsController> _logger;public ProductsController(ProductContext context, ILogger<ProductsController> logger)
{_logger = logger;// ...
}

假设，现在您的团队决定要抓取客户端请求获取 100 条或更多条记录的频率相关的遥测数据。

将下面的代码放入 GetProducts 中：

if (request.Limit >= 100)_logger.LogInformation("Requesting more than 100 products.");

请确保有一个已存在的临时文件夹来核查日志，例如：C:\temp\BuildRestApiNetCore\。

一条日志记录看起来可能是这样的：

{"Timestamp": "2020-07-12 10:30:30.8960","Level": "INFO","Logger": "BuildRestApiNetCore.Controllers.ProductsController","Action": "GetProducts","Message": "Requesting more than 100 products."
}

带动词的 REST Endpoints

深吸一口气，然后畅快地呼出。该 API 差不多可以投入生产环境了，而且只用了很少的代码。现在，我将快速转向 POST、PUT、PATCH 和 DELETE 等 REST 特性的介绍。

POST Endpoint 接收带有新产品的 body，并将其添加到列表当中。此方法是非幂等的，因为它在调用时会创建新的资源。

将下面的代码放入 ProductsController 中：

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<Product> PostProduct([FromBody] Product product)
{try{_context.Products.Add(product);_context.SaveChanges();return new CreatedResult($"/products/{product.ProductNumber.ToLower()}", product);}catch (Exception e){_logger.LogWarning(e, "Unable to POST product.");return ValidationProblem(e.Message);}
}

ASP.NET 通过 ValidationProblem 自动处理异常。该验证将返回一条符合 RFC 7807 规范^[6]的响应，并带有一条消息。在实际的系统中，我建议确保不要暴露任何关于 API 的内部信息。将异常信息放在此处有助于客户端对代码进行故障排除，但安全性也很重要。我在这里选择包含错误信息主要是为了演示目的。此处还会将异常记录为警告，以避免记录大量的错误。当异常太多时，监控工具可能会呼叫值班人员。最佳实践是仅在可能需要人工干预的灾难性故障期间记录错误。

使用 swagger 工具，curl 命令为：

curl -i -X POST http://localhost:5000/v1/products-H "accept: application/json"-H "Content-Type: application/json"-d "{\"productNumber\":\"string\",\"name\":\"string\",\"price\":10,\"department\":\"string\"}"

当请求有问题时，API 会如下响应：

{"errors": {},"type": "https://tools.ietf.org/html/rfc7231#p-6.5.1","title":"One or more validation errors occurred.","status": 400,"detail": "An item with the same key has already been added. Key: string","traceId":"|c445a403-43564e0626f9af50."
}

400 (Bad Request) 响应表示请求中的用户错误。因为无法信任用户发送有效数据，所以 API 会记录一个警告。

请注意，如果成功，POST 将返回带有 Location 的 201：

HTTP/1.1 201 Created
Date: Mon, 13 Jul 2020 22:52:46 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 76
Location: /products/bc916
api-supported-versions: 1.0

这将引导客户端转向新资源。此处，转向 GET Endpoint 是个好主意：

[HttpGet]
[Route("{productNumber}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public ActionResult<Product> GetProductByProductNumber([FromRoute] string productNumber)
{var productDb = _context.Products.FirstOrDefault(p => p.ProductNumber.Equals(productNumber, StringComparison.InvariantCultureIgnoreCase));if (productDb == null) return NotFound();return Ok(productDb);
}

404 响应表示该资源在 API 中尚不存在，但可能会在将来的某个时候变得可用。

PUT 是类似的：

[HttpPut]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<Product> PutProduct([FromBody] Product product)
{try{var productDb = _context.Products.FirstOrDefault(p => p.ProductNumber.Equals(product.ProductNumber, StringComparison.InvariantCultureIgnoreCase));if (productDb == null) return NotFound();productDb.Name = product.Name;productDb.Price = product.Price;productDb.Department = product.Department;_context.SaveChanges();return Ok(product);}catch (Exception e){_logger.LogWarning(e, "Unable to PUT product.");return ValidationProblem(e.Message);}
}

在 REST 设计中，PUT 允许对整个资源进行更新。它是幂等的，因为多次相同的请求不会改变资源的数量。

就像 GET 404 响应一样，表示该资源不可用于更新，但这可能在稍后发生改变。另外，ASP.NET 提供现成的模型绑定验证。接下来，尝试一下使用错误的数据更新现有资源。

下面的 JSON 是您可能看到的 Bad Request 的响应：

{"errors": {"Price": ["The price field is required."]},"type": "https://tools.ietf.org/html/rfc7231#p-6.5.1","title": "One or more validation errors occurred.","status": 400,"traceId": "|c445a409-43564e0626f9af50."
}

PATCH 是所有动词中最复杂的，因为它通过 JSON Patch 文档^[7]仅更新资源的一部分。

庆幸的是 .NET Core 提供了一个 NuGet 包：

dotnet add package Microsoft.AspNetCore.Mvc.NewtonsoftJson

然后，在 ConfigureServices 中启用它：

services.AddControllers().AddNewtonsoftJson();

下面是 PATCH Endpoint，记得添加 using Microsoft.AspNetCore.JsonPatch：

[HttpPatch]
[Route("{productNumber}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<Product> PatchProduct([FromRoute] string productNumber, [FromBody] JsonPatchDocument<Product> patch)
{try{var productDb = _context.Products.FirstOrDefault(p => p.ProductNumber.Equals(productNumber, StringComparison.InvariantCultureIgnoreCase));if (productDb == null) return NotFound();patch.ApplyTo(productDb, ModelState);if (!ModelState.IsValid || !TryValidateModel(productDb)) return ValidationProblem(ModelState);_context.SaveChanges();return Ok(productDb);}catch (Exception e){_logger.LogWarning(e, "Unable to PATCH product.");return ValidationProblem(e.Message);}
}

我希望您看到一种含有不同状态码响应类型的模式开始浮现。200 OK 表示成功，400 Bad Request 表示用户错误。当 patch 被应用后，将会在 ModelState 中追加所有的验证错误。仔细看一下进行模型绑定的 JsonPatchDocument 和应用更改的 ApplyTo。这就是将 JSON Patch 文档应用到数据库中现有产品的方式。像所有其它 Endpoints 一样，异常会被记录并包含在响应中。与其它动词一样，404 (Not Found) 响应表示相同的情形。响应状态码的一致性有助于客户端处理所有可能的场景。

一个 JSON patch 请求的 body 大概如下所示：

[{"op": "replace","path": "price","value": 13.67
}]

模型绑定验证规则依然适用于 patch 操作，以保持数据的完整性。请注意，patch 操作被包装在一个数组中，因此它支持任意的操作列表。

下图是 curl 中请求 PATCH 的结果：

最后一站，DELETE 方法：

[HttpDelete]
[Route("{productNumber}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public ActionResult<Product> DeleteProduct([FromRoute] string productNumber)
{var productDb = _context.Products.FirstOrDefault(p => p.ProductNumber.Equals(productNumber, StringComparison.InvariantCultureIgnoreCase));if (productDb == null) return NotFound();_context.Products.Remove(productDb);_context.SaveChanges();return NoContent();
}

它的状态码响应是 No Content：

HTTP/1.1 204 No Content
Date: Tue, 14 Jul 2020 22:59:20 GMT
Server: Kestrel
api-supported-versions: 1.0

此状态向客户端发出信号，表示资源不再可用，因为响应主体为空。如果需要异步后台进程来清理数据，则响应也可以为 204 (Accepted)。在实际系统中，有时最好使用软删除，以允许在审核期间进行回滚。删除数据时，请确保遵守 GPDR 或适用于该数据的任一策略。

总结

.NET Core 在您的工具袋中添加许多有用的特性，从而让使用 REST API 变得更加轻松，将诸如文档、验证、日志记录和 PATCH 请求等复杂的用例变得更易于实现。