创建一个好的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!](https://image.evget.com/2023/01/13/1zekus0bthroswwgb.png)
命名约定
虽然在命名方面存在差异,但很常见的是,技术巨头的url总是使用小写字母。如果有必要使用一个由多个名词组成的单词,请尝试使用下划线(_)或破折号(-)将它们分开。示例如下:
![掌握这七个小技巧,轻松构建优秀的Web API!](https://image.evget.com/2023/01/13/2bz18wbxy8emu4bf7.png)
名词是复数还是单数?
如前所述,应该使用名词替代动词,但常见的问题是这些名词是用复数还是单数来写。
答案是没有正确的形式,部分开发者更喜欢用复数形式,因为这样它们表示一组可以是一个或多个的特征。当使用单数时,将端点限制为一项。
无论您使用哪种方式,目标始终是简化。
![掌握这七个小技巧,轻松构建优秀的Web API!](https://image.evget.com/2023/01/13/3eenu8n8ksvawbr03.png)
版本
API在第一次发布后不断发展是很常见的,因此为同一个API创建不同版本非常重要。许多公司选择在端点中明确表示,即通过字母“v”+版本号表示API版本。所以,通常在第一个版本中我们看到“v1”
对API进行版本控制有助于系统维护,使用v1端点的系统不会受到影响,因为所有更改都在另一个端点上可用——在本例中为v2。
但重要的是要明确这不是强制性的,许多公司通常不为他们的API创建版本,在这种情况下,将创建新的API并替换就得API。
![掌握这七个小技巧,轻松构建优秀的Web API!](https://image.evget.com/2023/01/13/40tfld011g19g1au1.png)
Tip 2:使用正确的HTTP动词
首先,开发人员应该学习HTTP的基础知识。
以下是主要的HTTP动词及其各自的功能:
![掌握这七个小技巧,轻松构建优秀的Web API!](https://image.evget.com/2023/01/13/54mmct0ic11c30sdx.png)
使用正确的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!](https://image.evget.com/2023/01/13/6io2pfclmfr6fde8a.png)
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中文网!
标签:Web,product,HTTP,七个,API,products,端点,使用 From: https://www.cnblogs.com/AABBbaby/p/17088140.html