掌握这七个小技巧，轻松构建优秀的WebAPI！

　　创建一个好的API需要特别注意一些事情，本文介绍的7个技巧将帮助开发人员在使用ASP.NET Core时轻松创建更好的API。
　　好的API由许多因素组成，包括日志、文档、性能等。随着Web API的流行，实现好的API是作为Web开发人员的日常工作中非常常见的任务，特别是使用Microsoft的技术，如ASP.NET Core。
　　Telerik JustMock官方最新版免费下载试用，历史版本下载，在线文档和帮助文件下载-慧都网Tip 1：写出好的端点
　　总是使用名词
　　在创建端点时，总是使用名词替代动词，请看下面错误的方法和正确的方法。
　　命名约定
　　虽然在命名方面存在差异，但很常见的是，技术巨头的url总是使用小写字母。如果有必要使用一个由多个名词组成的单词，请尝试使用下划线(_)或破折号(-)将它们分开。示例如下：
　　名词是复数还是单数？
　　如前所述，应该使用名词替代动词，但常见的问题是这些名词是用复数还是单数来写。
　　答案是没有正确的形式，部分开发者更喜欢用复数形式，因为这样它们表示一组可以是一个或多个的特征。当使用单数时，将端点限制为一项。
　　无论您使用哪种方式，目标始终是简化。
　　版本
　　API在第一次发布后不断发展是很常见的，因此为同一个API创建不同版本非常重要。许多公司选择在端点中明确表示，即通过字母＂v＂+版本号表示API版本。所以，通常在第一个版本中我们看到＂v1＂
　　对API进行版本控制有助于系统维护，使用v1端点的系统不会受到影响，因为所有更改都在另一个端点上可用——在本例中为v2。
　　但重要的是要明确这不是强制性的，许多公司通常不为他们的API创建版本，在这种情况下，将创建新的API并替换就得API。
　　Tip 2：使用正确的HTTP动词
　　首先，开发人员应该学习HTTP的基础知识。
　　以下是主要的HTTP动词及其各自的功能：
　　使用正确的HTTP状态码
　　HTTP中一个有价值的特性是状态，这些状态在服务器响应中返回，这取决于请求中发送的操作结果，可能是命中，也可能是失败。不管结果如何，有几种类型的状态——由开发人员根据情况实现正确的状态。
　　例如，API通过查询字符串接收对方的id。如果数据库中存在该id, API将返回相应对方的数据。如果不是，API返回一个带有详细描述的错误。以下是两种场景:
　　1. 发现对方 HTTP/1.1 200 OK Content-Type: text/html  { ＂status＂: ＂success＂, ＂data＂: { { ＂idSeller＂: ＂100002132＂, ＂name＂: ＂SellerExample＂, ＂offerCode＂: ＂4＂, ＂smallSeller＂: false } } }
　　2. 未发现对方 HTTP/1.1 404 Not Found Content-Type: text/html  { ＂status＂: ＂error＂, ＂messages＂: [ { ＂code＂: ＂018＂, ＂message＂: ＂Seller not found＂ } ] }
　　另一个要点是返回状态的一致使用。例如，在success这个例子中，每个动词都有一个常用的模式。 GET: 200 OK POST: 201 Created PUT: 200 OK DELETE: 204 No Content PATCH: 200 OK Tip 3：避免将业务规则放在端点上
　　API的端点用于数据的输入和输出，因此最好的选择是创建一个类(通常称为Service)，将业务规则放在其中，然后在端点上调用服务类的主方法。如下面的例子所示：
　　❌ Wrong: app.MapPost(＂v1/products＂, (Product product, ProductDbContext dbContext) => { string errorMessage = string.Empty;  if (string.IsNullOrEmpty(product.Name)) errorMessage += ＂Name is mandatory＂;  if (string.IsNullOrEmpty(product.Category)) errorMessage += ＂Category is mandatory＂;  if (!string.IsNullOrEmpty(product.Name)) Results.BadRequest(＂Error creating the product＂);  else { dbContext.Products.Add(product); dbContext.SaveChanges(); return Results.Ok(); }  }).WithName(＂CreateProduct＂);
　　✅ Correct: app.MapPost(＂v1/products＂, (ProductService service, Product product) => { var resultMessage = service.Create(product);  if (!string.IsNullOrEmpty(resultMessage)) Results.BadRequest(#34;Error creating the product, error validation: {resultMessage}＂);  return Results.Ok();  }).WithName(＂CreateProduct＂);Tip 4：使用分页和过滤
　　应用程序随着时间的推移而增长是很常见的，允许API使用者根据需要选择只获得一定数量的项是很重要的，对此的一个建议是分页。
　　要实现分页而不要求数据库提供太多性能，最好的方法是提供可以＂切割＂记录集合的参数(标识符)和数量限制器。
　　你可以在下面看到一个好的和坏的例子，在第一个示例中，没有分页选项或限制。在第二种情况下，可以在端点路由中注意到这些参数。
　　Tip 5：使运行状况端点可用
　　让所有消费者都可以使用Health路由是一种很好的实践，顾名思义，该路径用于检查API的运行状况。在这种情况下，不仅API可用，而且可以检查API依赖关系并返回在每个API中获得的结果。
　　例如，在需要在外部API中生成令牌的API中，开发人员可以检入运行状况端点(如果该外部API可用)并在运行状况路由中返回检查结果。
　　因此，在API返回错误500(内部服务器错误)的情况下，消费者可以快速知道问题的原因可能在哪里，下面是运行状况端点的示例。
　　GET - v1/products/health app.MapGet(＂v1/products/health＂, (ProductService service) => { var externalAPIResponse = service.ExternalAPIHealthVerify(); return Results.Ok(#34;External API response: {externalAPIResponse.StatusCode} - {externalAPIResponse.Message}＂);  }).WithName(＂Health＂);Tip 6：使用API缓存
　　缓存是一种用于存储频繁使用的数据的技术，它非常有用，因为它旨在通过将数据存储在易于访问的地方来获得性能并减少web/数据库服务的负载，这些地方可以是内存内缓存(服务器的内存)、持久进程内缓存(文件或数据库)或分布式缓存(多进程)。
　　下面可以看到一个在ASP. NET Core Web API中实现内存缓存的例子。 app.MapGet (＂v1/products＂, (ProductService service) => { const string ProductsKey = ＂_Products＂;  if (!cache.TryGetValue(ProductsKey, out List products)) { products = service.GetAll(); var cacheEntryOptions = new MemoryCacheEntryOptions { AbsoluteExpiration = DateTime.Now.AddMinutes(3), SlidingExpiration = TimeSpan.FromMinutes(2), Size = 1024, }; cache.Set(ProductsKey, products, cacheEntryOptions); } return Results.Ok(products);  }).WithName(＂GetProducts＂);Tip 7：编写好的文档
　　在开发API时，编写好的文档是必不可少的——毕竟，开发人员将通过文档实现API的使用者。
　　大公司使用彼此非常相似的模型来提供关于其API的文档，它通常是一个非常简单的网页，包含了从头开始创建的所需的所有信息。
　　以下是良好文档的一些要求。 对API函数做一个简单的描述，始终添加关于任何业务规则的重要细节。例如:＂要取消购买，您需要在下订单后等待24小时……＂ 始终将请求和响应分开，对于它们中的每一个，提供HTTP谓词和要访问的路由，并在Request中发送并在Response中返回一个数据示例。 如果API包含一些复杂性，请始终提供流程流程图——使用图像描述流程比使用文字描述流程更直观。