当前位置: 首页 > 更新动态

掌握这七个小技巧,轻松构建优秀的Web API!

发布时间:2023-02-02

创建一个好的API需要特别注意一些事情,本文介绍的7个技巧将帮助开发人员在使用ASP.NET Core时轻松创建更好的API。

好的API由许多因素组成,包括日志、文档、性能等。随着Web API的流行,实现好的API是作为Web开发人员的日常工作中非常常见的任务,特别是使用Microsoft的技术,如ASP.NET Core。

Telerik UI for ASP.NET Core 新版下载

Telerik_KendoUI产品技术交流群:726377843    欢迎一起进群讨论

Tip 1:写出好的端点

总是使用名词

在创建端点时,总是使用名词替代动词,请看下面错误的方法和正确的方法。

掌握这七个小技巧,轻松构建优秀的Web API!

命名约定

虽然在命名方面存在差异,但很常见的是,技术巨头的url总是使用小写字母。如果有必要使用一个由多个名词组成的单词,请尝试使用下划线(_)或破折号(-)将它们分开。示例如下:

掌握这七个小技巧,轻松构建优秀的Web API!

名词是复数还是单数?

如前所述,应该使用名词替代动词,但常见的问题是这些名词是用复数还是单数来写。

答案是没有正确的形式,部分开发者更喜欢用复数形式,因为这样它们表示一组可以是一个或多个的特征。当使用单数时,将端点限制为一项。

无论您使用哪种方式,目标始终是简化。

掌握这七个小技巧,轻松构建优秀的Web API!

版本

API在第一次发布后不断发展是很常见的,因此为同一个API创建不同版本非常重要。许多公司选择在端点中明确表示,即通过字母“v”+版本号表示API版本。所以,通常在第一个版本中我们看到“v1”

对API进行版本控制有助于系统维护,使用v1端点的系统不会受到影响,因为所有更改都在另一个端点上可用——在本例中为v2。

但重要的是要明确这不是强制性的,许多公司通常不为他们的API创建版本,在这种情况下,将创建新的API并替换就得API。

掌握这七个小技巧,轻松构建优秀的Web API!
Tip 2:使用正确的HTTP动词

首先,开发人员应该学习HTTP的基础知识。

以下是主要的HTTP动词及其各自的功能:

掌握这七个小技巧,轻松构建优秀的Web API!

使用正确的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使用者根据需要选择只获得一定数量的项是很重要的,对此的一个建议是分页。

要实现分页而不要求数据库提供太多性能,最好的方法是提供可以“切割”记录集合的参数(标识符)和数量限制器。

你可以在下面看到一个好的和坏的例子,在第一个示例中,没有分页选项或限制。在第二种情况下,可以在端点路由中注意到这些参数。

掌握这七个小技巧,轻松构建优秀的Web 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包含一些复杂性,请始终提供流程流程图——使用图像描述流程比使用文字描述流程更直观。

了解最新Kendo UI最新资讯,请关注Telerik中文网!

扫码咨询
电话咨询
023-68661681
返回
顶部