创建一个好的API需要特别注意一些事情，本文介绍的7个技巧将帮助开发人员在使用ASP.NET Core时轻松创建更好的API。
好的API由许多因素组成，包括日志、文档、性能等。随着Web API的流行，实现好的API是作为Web开发人员的日常工作中非常常见的任务，特别是使用Microsoft的技术，如ASP.NET Core。
Telerik_KendoUI产品技术交流群：726377843 欢迎一起进群讨论
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($"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($"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<Product> 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包含一些复杂性，请始终提供流程流程图——使用图像描述流程比使用文字描述流程更直观。