創(chuàng)建一個(gè)好的API需要特別注意一些事情，本文介紹的7個(gè)技巧將幫助開發(fā)人員在使用ASP.NET Core時(shí)輕松創(chuàng)建更好的API。

好的API由許多因素組成，包括日志、文檔、性能等。隨著Web API的流行，實(shí)現(xiàn)好的API是作為Web開發(fā)人員的日常工作中非常常見的任務(wù)，特別是使用Microsoft的技術(shù)，如ASP.NET Core。

Telerik_KendoUI產(chǎn)品技術(shù)交流群：726377843    歡迎一起進(jìn)群討論

Tip 1：寫出好的端點(diǎn)

總是使用名詞

在創(chuàng)建端點(diǎn)時(shí)，總是使用名詞替代動(dòng)詞，請(qǐng)看下面錯(cuò)誤的方法和正確的方法。

命名約定

 雖然在命名方面存在差異，但很常見的是，技術(shù)巨頭的url總是使用小寫字母。如果有必要使用一個(gè)由多個(gè)名詞組成的單詞，請(qǐng)嘗試使用下劃線(_)或破折號(hào)(-)將它們分開。示例如下：

名詞是復(fù)數(shù)還是單數(shù)？

如前所述，應(yīng)該使用名詞替代動(dòng)詞，但常見的問題是這些名詞是用復(fù)數(shù)還是單數(shù)來寫。

答案是沒有正確的形式，部分開發(fā)者更喜歡用復(fù)數(shù)形式，因?yàn)檫@樣它們表示一組可以是一個(gè)或多個(gè)的特征。當(dāng)使用單數(shù)時(shí)，將端點(diǎn)限制為一項(xiàng)。

無論您使用哪種方式，目標(biāo)始終是簡化。

版本

API在第一次發(fā)布后不斷發(fā)展是很常見的，因此為同一個(gè)API創(chuàng)建不同版本非常重要。許多公司選擇在端點(diǎn)中明確表示，即通過字母“v”+版本號(hào)表示API版本。所以，通常在第一個(gè)版本中我們看到“v1”

對(duì)API進(jìn)行版本控制有助于系統(tǒng)維護(hù)，使用v1端點(diǎn)的系統(tǒng)不會(huì)受到影響，因?yàn)樗懈亩荚诹硪粋€(gè)端點(diǎn)上可用——在本例中為v2。

但重要的是要明確這不是強(qiáng)制性的，許多公司通常不為他們的API創(chuàng)建版本，在這種情況下，將創(chuàng)建新的API并替換就得API。

Tip 2：使用正確的HTTP動(dòng)詞

首先，開發(fā)人員應(yīng)該學(xué)習(xí)HTTP的基礎(chǔ)知識(shí)。

以下是主要的HTTP動(dòng)詞及其各自的功能：

使用正確的HTTP狀態(tài)碼

HTTP中一個(gè)有價(jià)值的特性是狀態(tài)，這些狀態(tài)在服務(wù)器響應(yīng)中返回，這取決于請(qǐng)求中發(fā)送的操作結(jié)果，可能是命中，也可能是失敗。不管結(jié)果如何，有幾種類型的狀態(tài)——由開發(fā)人員根據(jù)情況實(shí)現(xiàn)正確的狀態(tài)。

例如，API通過查詢字符串接收對(duì)方的id。如果數(shù)據(jù)庫中存在該id, API將返回相應(yīng)對(duì)方的數(shù)據(jù)。如果不是，API返回一個(gè)帶有詳細(xì)描述的錯(cuò)誤。以下是兩種場景:

1. 發(fā)現(xiàn)對(duì)方

HTTP/1.1 200 OK
Content-Type: text/html

{
"status": "success",
"data":
{
{
"idSeller": "100002132",
"name": "SellerExample",
"offerCode": "4",
"smallSeller": false
}
}
}

2. 未發(fā)現(xiàn)對(duì)方

HTTP/1.1 404 Not Found
Content-Type: text/html

{
"status": "error",
"messages": [
{
"code": "018",
"message": "Seller not found"
}
]
}

另一個(gè)要點(diǎn)是返回狀態(tài)的一致使用。例如，在success這個(gè)例子中，每個(gè)動(dòng)詞都有一個(gè)常用的模式。

• GET: 200 OK
• POST: 201 Created
• PUT: 200 OK
• DELETE: 204 No Content
• PATCH: 200 OK

Tip 3：避免將業(yè)務(wù)規(guī)則放在端點(diǎn)上

API的端點(diǎn)用于數(shù)據(jù)的輸入和輸出，因此最好的選擇是創(chuàng)建一個(gè)類(通常稱為Service)，將業(yè)務(wù)規(guī)則放在其中，然后在端點(diǎn)上調(diào)用服務(wù)類的主方法。如下面的例子所示：

? 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：使用分頁和過濾

應(yīng)用程序隨著時(shí)間的推移而增長是很常見的，允許API使用者根據(jù)需要選擇只獲得一定數(shù)量的項(xiàng)是很重要的，對(duì)此的一個(gè)建議是分頁。

要實(shí)現(xiàn)分頁而不要求數(shù)據(jù)庫提供太多性能，最好的方法是提供可以“切割”記錄集合的參數(shù)(標(biāo)識(shí)符)和數(shù)量限制器。

你可以在下面看到一個(gè)好的和壞的例子，在第一個(gè)示例中，沒有分頁選項(xiàng)或限制。在第二種情況下，可以在端點(diǎn)路由中注意到這些參數(shù)。

Tip 5：使運(yùn)行狀況端點(diǎn)可用

讓所有消費(fèi)者都可以使用Health路由是一種很好的實(shí)踐，顧名思義，該路徑用于檢查API的運(yùn)行狀況。在這種情況下，不僅API可用，而且可以檢查API依賴關(guān)系并返回在每個(gè)API中獲得的結(jié)果。

例如，在需要在外部API中生成令牌的API中，開發(fā)人員可以檢入運(yùn)行狀況端點(diǎn)(如果該外部API可用)并在運(yùn)行狀況路由中返回檢查結(jié)果。

因此，在API返回錯(cuò)誤500(內(nèi)部服務(wù)器錯(cuò)誤)的情況下，消費(fèi)者可以快速知道問題的原因可能在哪里，下面是運(yùn)行狀況端點(diǎn)的示例。

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緩存

緩存是一種用于存儲(chǔ)頻繁使用的數(shù)據(jù)的技術(shù)，它非常有用，因?yàn)樗荚谕ㄟ^將數(shù)據(jù)存儲(chǔ)在易于訪問的地方來獲得性能并減少web/數(shù)據(jù)庫服務(wù)的負(fù)載，這些地方可以是內(nèi)存內(nèi)緩存(服務(wù)器的內(nèi)存)、持久進(jìn)程內(nèi)緩存(文件或數(shù)據(jù)庫)或分布式緩存(多進(jìn)程)。

下面可以看到一個(gè)在ASP. NET Core Web API中實(shí)現(xiàn)內(nèi)存緩存的例子。

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：編寫好的文檔

在開發(fā)API時(shí)，編寫好的文檔是必不可少的——畢竟，開發(fā)人員將通過文檔實(shí)現(xiàn)API的使用者。

大公司使用彼此非常相似的模型來提供關(guān)于其API的文檔，它通常是一個(gè)非常簡單的網(wǎng)頁，包含了從頭開始創(chuàng)建的所需的所有信息。

以下是良好文檔的一些要求。

• 對(duì)API函數(shù)做一個(gè)簡單的描述，始終添加關(guān)于任何業(yè)務(wù)規(guī)則的重要細(xì)節(jié)。例如:“要取消購買，您需要在下訂單后等待24小時(shí)……”
• 始終將請(qǐng)求和響應(yīng)分開，對(duì)于它們中的每一個(gè)，提供HTTP謂詞和要訪問的路由，并在Request中發(fā)送并在Response中返回一個(gè)數(shù)據(jù)示例。
• 如果API包含一些復(fù)雜性，請(qǐng)始終提供流程流程圖——使用圖像描述流程比使用文字描述流程更直觀。