本文說明實作、部署及操作 RESTful 網頁 API 的最佳實務。 它著重於請求處理、效能、可靠性、發佈與監控。 關於資源建模與 API 設計的指引,請參見 Web API 設計。
架構指引適用於各種實作語言與框架。 C# 範例說明了 ASP.NET Core 控制器。
正在處理請求
在實作處理請求的程式碼時,請考慮以下幾點。
保留 HTTP 方法語意,並實作冪等性
使用 GET 來回傳資源資料,使用 HEAD 來回傳沒有主體的回應標頭。 不要用任一種方法來建立、更新或刪除資源。
GET、HEAD、PUT 和 DELETE 必須是冪等的,因此重複相同請求的效果與執行一次相同。 例如,DELETE 會改變資源狀態,但重複它不會刪除額外的資源。 第一個 DELETE 請求可能會回傳 204(無內容),而後續請求則回傳 404(未找到)。
POST 和 PATCH 本身並非冪等。 將屬性設為某個值的 PATCH 操作可以是冪等,但如果是讓計數器增加,則不是冪等。 記錄哪些狀態變更操作客戶端可以安全重試。 如果你支援非冪等的操作重試,請實作並記錄服務如何防止重複執行造成的重複結果。 關於方法語意,請參見 HTTP 請求方法。
註記
有關實作指引,請參見 冪等消費者模式。 實務上,首先要判斷一個運算是否自然具有冪等性。 如果不是,就透過追蹤已處理的訊息 ID 並主動或被動處理重複訊息來施加人工冪性。
驗證請求資料,並控制欄位存取
定義請求與回應模型,只暴露 API 合約中的欄位。 將這些模型映射到儲存的資料,而不是直接將請求本文綁定到資料庫實體或回傳每個儲存的屬性。 避免呼叫者透過提交額外欄位來更改受保護屬性,並省略他們未被授權閱讀的屬性。 資料傳輸物件(DTO)是落實此界線的一種方式。 欲了解更多資訊,請參閱防止 ASP.NET Core 中的過度張貼。
在儲存變更前,先驗證所需的欄位、類型、範圍及商業規則。 如果你支援欄位選擇,請先驗證請求欄位是否符合允許清單和呼叫者的權限,再回傳僅包含這些欄位的回應。 也要將文件中記載的限制套用於篩選和排序。 對應的合約選項,請參見 「實作分頁與過濾」。
限制建立資源之 POST 動作的副作用
當 POST 請求建立資源時,應限制其影響於該資源及直接相關的資源。 例如,建立訂單也可能更新庫存並產生帳單資訊。 它不應該修改無關資訊。
避免執行過於頻繁的 POST、PUT 和 DELETE 作業
請避免根據 閒聊 作業設計 API。 每個請求都會帶來通訊協定、網路和計算負荷。 例如,執行 100 個較小的請求而非一個較大的批次請求,會在用戶端、網路及資源伺服器端產生額外開銷。 對於需要大量作業的工作負載,可以考慮使用有界批次請求,而非多個個別請求。
- 對集合傳送 GET 請求可以同時擷取多個資源。
- POST 請求可以包含多個新資源的詳細資訊,並將它們全部新增到同一集合中。
- PUT 請求可以替換集合中的整個資源集。
- DELETE 請求可以移除整個集合。
定義最大批次大小、有效載荷大小、執行時間及並行性。 指定批次是原子級還是可否部分成功,並為每個操作回傳結果。 授權並驗證批次中的每一個操作。
如果你使用 OData,可以使用 ASP.NET Core OData 來實作批次請求。 欲了解更多資訊,請參閱 ASP.NET Core OData 概述。
傳送回應時請遵循 HTTP 規範
回傳適當的 HTTP 狀態碼、標頭與正文格式,讓用戶端能解讀並處理回應。
例如,一個同步建立資源的 POST 操作,應該回傳 201(已建立)並在 Location 回應標頭中識別該資源。 接受後續處理工作的操作可以回傳 202(已接受),但該回應並不表示該工作已成功。 不要包含 204(無內容)或 304(未修改)的回應正文。 欲了解更多資訊,請參閱 HTTP 請求方法。
支援內容協商
回應主體可以包含不同格式的資料,例如 JSON 或 XML。 用戶端可以使用 Accept 請求標頭來指定支援的媒體類型。 例如,用戶端請求影像時可能會指定 image/jpeg, image/gif, image/png。 回傳支援的表示方式,並在 Content-Type 回應標頭中標示其媒體類型。
如果客戶端沒有指定 Accept 標頭,就使用有文件記錄的預設格式。 ASP.NET Core 控制器預設使用 JSON 格式化器。 請定義當 API 無法產生請求的表示時會發生什麼事。 例如,設定 API 回傳 406(不可接受),而不是默默回傳不支援的格式。 欲了解更多資訊,請參閱 在 ASP.NET Core Web API 中格式化回應資料。
對於有本文的請求,請檢查請求的 Content-Type,並只接受該作業支援的格式。 回傳 415(不支援媒體類型)以表示不支援格式。 此檢查與透過 Accept的回應協商是分開的。 在 ASP.NET Core 中,設定輸入格式化器,並在需要限制操作請求格式時使用[Consumes]。 欲了解更多資訊,請參閱使用 ASP.NET Core 建立網頁 API。
實作所選的 API 版本管理策略
在應用程式和閘道器中,持續套用 你設計時選擇的版本設定策略。 將請求路由至處理器以及所選版本的回應架構。 定義被遺漏、格式錯誤或不支援的版本識別碼之行為,而不是默默改變現有呼叫者收到的契約。
保留支援版本的請求與回應契約。 當你引入破壞性變更時,請提供新版本,並讓較早且仍受支援的版本可供使用。 處理由較舊的呼叫端提出且省略新新增選填欄位的請求。 欲了解更多資訊,請參閱 API 版本管理與相容性。
保持產生的資源連結與快取表示與所選版本一致。 對於標頭式版本控制,請確保快取能區分不同版本的請求,而非僅依賴 URI。
解析並授權租用戶內容
對於 多租戶 API,請確定每個請求的租戶,並驗證已認證的呼叫者是否能存取該租戶。 僅將路徑、主機名稱和標頭中的租戶識別碼視為路由輸入。 如需詳細資訊,請參閱 在多租戶解決方案中將請求映射到租戶。
查詢或更新資料時,以及將工作交給背景處理者時,請一致使用授權租戶上下文。 若應用程式或閘道快取儲存租戶專屬資料,請在快取鍵中包含租戶識別碼。 關於閘道的具體指引,請參閱 支援多租戶的 API 管理功能。
提供連結以支援 HATEOAS 式導覽和資源探索
超文本作為應用程式狀態引擎(HATEOAS)使用連結幫助客戶端發現與導航資源。 例如,包含顧客資料的回應可以包含該顧客訂單的連結。 描述每個連結資源所支援的操作,如 GET、POST、PUT 和 DELETE,並提供相應的 URI。 欲了解更多資訊,請參閱 API 設計。
以下範例使用應用程式定義的連結表示法。 記錄其慣例,而非假設客戶能解讀自訂連結欄位。 客戶的 GET 請求會傳回該客戶訂單的連結:
GET https://api.contoso.com/customers/2 HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
...
Content-Type: application/json; charset=utf-8
...
Content-Length: ...
{"customerId": 2,"customerName": "Bert","links": [
{"rel": "self",
"href": "https://api.contoso.com/customers/2",
"action": "GET",
"types": ["text/xml","application/json"]},
{"rel": "self",
"href": "https://api.contoso.com/customers/2",
"action": "PUT",
"types": ["application/x-www-form-urlencoded"]},
{"rel": "self",
"href": "https://api.contoso.com/customers/2",
"action": "DELETE",
"types": []},
{"rel": "orders",
"href": "https://api.contoso.com/customers/2/orders",
"action": "GET",
"types": ["text/xml","application/json"]},
{"rel": "orders",
"href": "https://api.contoso.com/customers/2/orders",
"action": "POST",
"types": ["application/x-www-form-urlencoded"]}
]}
以下 Customer 記錄代表客戶資料。 其 Links 屬性包含 HATEOAS 連結。
public sealed record Customer(
int CustomerId,
string CustomerName,
IReadOnlyList<Link> Links);
public sealed record Link(
string Rel,
string Href,
string Action,
IReadOnlyList<string> Types);
GET 操作會從儲存中擷取客戶資料,建立包含其連結的 Customer 記錄,並回傳 JSON 回應。 每個連結都包括以下欄位:
- 回傳資源與連結資源之間的關係
Rel()。 在此範例中,self指的是客戶,orders指的是客戶的訂單集合。 - 連結所描述之物件的超連結(
Href),其形式為 URI。 - 可以傳送到 URI 的 HTTP 請求類型(
Action)。 - 根據請求的類型,HTTP 請求中應提供的資料格式 (
Types) 或在回應中可以返回的資料格式。
範例 HTTP 回應中顯示的 HATEOAS 連結表明,用戶端應用程式可以執行以下作業:
- 向
https://api.contoso.com/customers/2發出 HTTP GET 請求,以 XML 或 JSON 擷取客戶詳細資料。 - 對
https://api.contoso.com/customers/2發出的 HTTP PUT 請求,用來修改客戶資料。 請求本文使用以下格式:application/x-www-form-urlencoded。 - 對
https://api.contoso.com/customers/2發出 HTTP DELETE 請求,以刪除客戶紀錄。 此操作不需請求實體,且不會傳回回應主體。 - HTTP GET 請求
https://api.contoso.com/customers/2/orders用來取得客戶的訂單,格式為 XML 或 JSON。 - 一個對
https://api.contoso.com/customers/2/orders發出 HTTP POST 請求,以為客戶建立訂單。 請求本文使用以下格式:application/x-www-form-urlencoded。
處理例外狀況
如果某操作拋出未被處理的例外,請參考以下指引。
擷取例外狀況,並向用戶端傳回有意義的回應。
一致地處理例外,並回傳一個安全且可與客戶共享的有意義錯誤回應。 不要在生產回應中回傳例外物件、堆疊追蹤或內部實作細節。 回傳反映失敗的 HTTP 狀態碼,而不是每次都回傳狀態碼 500。 例如,若使用者請求導致資料庫更新違反限制(例如嘗試刪除有未完成訂單的客戶),則回傳 409(衝突)及安全的說明。 回傳 400(錯誤請求)表示格式不正確的輸入或請求驗證失敗,而非意外的伺服器故障。 關於 HTTP 狀態定義,請參見 狀態碼。 關於實作指引,請參見 在 ASP.NET Core 中處理錯誤。
以下控制器將預期的網域結果映射到 HTTP 回應。 其儲存庫操作會檢查授權與未完成的訂單,作為刪除作業的一部分。 意外失敗會傳遞到集中的例外處理系統,而非在每個動作中被悄悄捕捉。
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Authorize]
[Route("customers")]
public sealed class CustomersController(ICustomerRepository repository) : ControllerBase
{
[HttpDelete("{id:int}")]
public async Task<IActionResult> DeleteCustomer(int id, CancellationToken cancellationToken)
{
var outcome = await repository.DeleteAuthorizedAsync(id, User, cancellationToken);
return outcome switch
{
DeleteOutcome.Deleted => NoContent(),
DeleteOutcome.NotFound => NotFound(),
DeleteOutcome.HasOutstandingOrders => Conflict(new ProblemDetails
{
Status = StatusCodes.Status409Conflict,
Title = "The customer has outstanding orders."
}),
_ => throw new InvalidOperationException("Unknown deletion outcome.")
};
}
}
public enum DeleteOutcome
{
Deleted,
NotFound,
HasOutstandingOrders
}
Important
不要包含可能對試圖未經授權存取你 API 的攻擊者有用的資訊。
主機層可以在請求到達 API 前就拒絕它們。 例如,認證失敗可能導致 401(未授權)回應。 完成身分驗證後,確認呼叫者被授權存取所請求的資源。 授權失敗時,請返回 403(禁止存取)。
以一致的方法處理例外狀況,並記錄有關錯誤的資訊。
為了一致處理例外,建議在整個網頁 API 中實施全域錯誤處理策略。 在伺服器上記錄診斷資訊,但排除機密、存取權杖及敏感個人資料。 在撰寫日誌前,先遮蔽敏感值,並限制授權使用者存取日誌。 欲了解更多資訊,請參閱 監控與威脅偵測的架構策略。
在 ASP.NET Core 中,使用例外處理中介軟體與 Problem Details 回應以建立一致的錯誤合約。 設定生產回應省略診斷細節,並包含相關識別碼,支援團隊可用來定位對應的日誌。 如需詳細資訊,請參閱處理 ASP.NET Core 中的錯誤。
區分用戶端錯誤和伺服器端錯誤
用戶端錯誤使用HTTP 4xx 狀態碼,伺服器錯誤則使用HTTP 5xx 狀態碼。 在錯誤回應中保持此區分。
最佳化用戶端資料存取
頻繁的請求與大量回應會使網路成為瓶頸。 在實作資源檢索與更新時,減少不必要的傳輸。
支援用戶端快取
使用 Cache-Control 回應標頭來指定客戶端與中介伺服器是否能儲存回應,以及回應保持新鮮的時間。
以下範例顯示了 HTTP GET 請求及其相應的回應,其中包括 Cache-Control 標頭:
GET https://api.contoso.com/orders/2 HTTP/1.1
HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: application/json
Content-Length: 59
{"orderId":2,"productId":4,"quantity":2,"orderValue":10.00}
在這個例子中,回應會保持新鮮 600 秒。 該 private 指令允許儲存在私有快取中,例如瀏覽器快取,但禁止在共享快取中儲存。 僅將 public 用於可安全跨通話者分享的回應。 對於不得儲存的敏感回應,請使用 no-store。
在 ASP.NET Core 控制器中,先設定快取標頭,然後再回傳回應:
Response.GetTypedHeaders().CacheControl = new Microsoft.Net.Http.Headers.CacheControlHeaderValue
{
Private = true,
MaxAge = TimeSpan.FromMinutes(10)
};
註記
該 no-cache 指令允許儲存,但要求在重複使用前重新驗證。 用 no-store 來禁止儲存。
API 控制其回應中的快取政策及驗證器。 用戶端和中介伺服器會利用這些資訊來管理快取。 將這些標頭設定一致,讓呼叫者能重複使用回應,避免不必要的資料傳輸。
要判斷 max-age,請考慮工作負載能容忍多少過時程度。 資源可以在快取回應仍為新鮮時變更。 當新鮮度過期時,快取可以重新驗證回應,而不是丟棄回應並重新下載整個資源表述。 不要用較長的新鮮度存留時間來處理需要即時可見變更的資料。
提供 ETags 以最佳化查詢處理
實體標籤(ETag)是一種不透明的驗證器,用於選取的資源表示。 客戶端可以用快取回應保留該資料,並送回 If-None-Match 來檢查資源表述是否改變。 匹配的 GET 或 HEAD 請求回傳 304(未修改),且無回應主體。
產生一個在應用程式實例間保持一致且表示方式改變時會改變的驗證器。
以下控制器會雜湊它回傳的精確 JSON 位元組,並重用應用程式已設定的 JSON 選項。
FileContentResult套用 ASP.NET Core 條件式回應處理,無需自訂結果包裝器。 儲存庫只會回傳呼叫者被授權讀取的訂單。 在主機應用程式中設定認證與授權。
using System.Security.Cryptography;
using System.Text.Json;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;
using Microsoft.Net.Http.Headers;
[ApiController]
[Authorize]
[Route("orders")]
public sealed class OrdersController(IOrderRepository repository,IOptions<JsonOptions> jsonOptions) : ControllerBase
{
[HttpGet("{id:int}")]
[HttpHead("{id:int}")]
public async Task<IActionResult> GetOrder(int id, CancellationToken cancellationToken)
{
var order = await repository.FindAuthorizedAsync(id, User, cancellationToken);
if (order is null)
{
return NotFound();
}
var payload = JsonSerializer.SerializeToUtf8Bytes(order, jsonOptions.Value.JsonSerializerOptions);
var etag = new EntityTagHeaderValue($"\"{Convert.ToHexString(SHA256.HashData(payload))}\"");
Response.GetTypedHeaders().CacheControl = new CacheControlHeaderValue
{
Private = true,
MaxAge = TimeSpan.FromMinutes(10)
};
return new FileContentResult(payload, "application/json")
{
EntityTag = etag
};
}
}
此範例會緩衝表示並讀取順序,即使是條件請求。 僅用於受限且不敏感的回應。 對於大型資源,可以考慮使用一個儲存版本的標記,當所選表示改變時它會改變,這樣你可以在不產生完整有效載荷的情況下驗證請求。 若內容協商、壓縮或閘道轉換改變表示方式,請確保驗證欄位與快取變異對該表示仍維持正確。
回應包含 ETag 與快取政策。 以下範例展示了顯示 JSON 主體 SHA-256 雜湊值的前 16 個十六進位字元(64 位元),後接 ...,為簡潔起見。 實際標頭包含不含省略號的完整雜湊值。
HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: application/json
ETag: "3097D1FD51082205..."
Content-Length: 59
{"orderId":2,"productId":4,"quantity":2,"orderValue":10.00}
提示
對於包含敏感資料的回應,請使用 Cache-Control: no-store。 對於其他可快取的使用者專屬回應,請使用 private 以防止儲存在共享快取中。 關於實作考量,請參見 ASP.NET Core 中的回應快取中介軟體。
支援條件式 GET 請求,讓呼叫者能在不下載未更改的表述內容的情況下重新驗證快取回應。 實作以下請求與回應行為:
接受在
If-None-Match標頭中提供 ETag 的條件式 GET 要求,例如:GET https://api.contoso.com/orders/2 HTTP/1.1 If-None-Match: "3097D1FD51082205..."比較當前請求資源的 ETag(此例為順序 2)與條件
If-None-Match。若條件符合,則回傳 304(未修改),且不含回應主體。
如果條件不符,則回傳 200(OK),並傳回目前的表述內容。
若請求的資源已不存在,請回傳 404(未找到)。
註記
ETag 不會讓回應安全放進快取。 持續套用快取指令,包括條件式與錯誤回應,並對敏感資料使用 no-store。
盡可能使用框架對條件式要求的支援。 如果你自己實作比較,請處理所有提供的實體標籤、通配符條件,以及弱與強比較規則,而不是只比較第一個標籤。 在 304(未修改)回應中加入適當的 ETag 與快取標頭,並在回傳資源中繼資料前執行授權。
提示
儲存的驗證標記可以讓你在不取得完整資源的情況下檢查表述是否改變。 當資源龐大或取回成本高時,此方法可減少資料傳輸與處理。
使用 ETag 來支援樂觀併發控制
為防止更新遺失,請對照資源目前的 ETag 評估 If-Match 狀態變更請求的前置條件。 這讓 API 可以根據其他操作已經修改過的表示來拒絕變更。 實作以下行為:
接受在
If-Match標頭中標示預期版本的更新請求。 以下 PUT 請求更新訂單 2。 它使用了先前的 GET 回應的 ETag,縮寫方式相同。 標籤識別的是現有的表示,而非新的請求實體:PUT https://api.contoso.com/orders/2 HTTP/1.1 If-Match: "3097D1FD51082205..." Content-Type: application/x-www-form-urlencoded Content-Length: 37 productId=3&quantity=5&orderValue=250比較當前請求資源的 ETag(此例為順序 2)與條件
If-Match。若前置條件符合,則以原子方式執行更新並回傳文件記載的成功回應,例如 204(無內容)。 僅因現有資源已更新,並不需要
Location標頭。 只有在成功的 PUT 回應符合 HTTP 對儲存表示的驗證器要求時,才回傳 ETag。若條件不符,則回傳 412(前置條件失敗)。 此範例不會回傳回應實體。
如果要更新的資源已不存在,請回傳 404(未找到)。
記錄成功與衝突回應,讓呼叫者判斷更新是否成功,或是否需要在提交下一次變更前取得目前的表述。
對於必須防止遺失更新的操作,請要求提供 If-Match 前置條件,若缺少則回傳 428(需要前置條件)。 對 If-Match 使用強式比較。
在應用程式記憶體中檢查版本,接著無條件地儲存,會產生競賽條件。 強制執行版本比較,並在資料存放區中以原子方式執行寫入。 例如,使用資料庫並行控制權杖,只有當儲存的版本仍與用來評估該請求的版本相符時,更新才會成功。
在 Entity Framework(EF)Core 中,將其設為並行權杖,並處理 DbUpdateConcurrencyException 而非覆寫並行變更。 在 API 的資料存取程式碼中,除非操作語意允許,否則不要自動替換預期版本並重試衝突的資料庫更新。 更多資訊請參見 處理並發衝突。
處理大型請求和回應
大型請求與回應實體會消耗 API 記憶體、頻寬及連線容量。 實施串流和資源限制,避免大規模傳輸耗盡服務資源。 處理大量資料時,請考慮以下幾點:
最佳化涉及大型物件的請求和回應
對於大型物件,如影像或其他二進位資料,支援串流上傳與下載。
使用非同步串流 API,讓伺服器為協商的 HTTP 版本選擇傳輸框定方式。 不要手動在回應的每個部分都加上 Transfer-Encoding: chunked。 串流不限於 HTTP/1.1 分塊編碼。 避免在應用程式記憶體中緩衝整個無界請求或回應。
在應用程式層與主機層設定請求體限制、上傳上限、逾時及取消政策。 在開始回應前,先以 413(內容過大)拒絕超大請求。
HTTP 壓縮可以減少傳輸大小,但代價是伺服器和用戶端需要額外的處理。 例如,客戶端可以傳送 Accept-Encoding: gzip。 如果伺服器回傳 gzip 壓縮的內容,請使用 Content-Encoding: gzip 識別編碼。
透過主機平台或中介軟體配置壓縮,並在客戶端與伺服器端衡量其 CPU 與頻寬的權衡。
- 避免重新壓縮已經壓縮過的檔案格式。
- 在啟用動態產生的 HTTPS 回應壓縮前,先評估壓縮風險(如 BREACH 等),並採取適當的緩解措施。 即使你在中介軟體中關閉了 HTTPS 壓縮,你的主機伺服器也可能設定成要施加壓縮。
- 確保快取變異與 ETag 在內容編碼變更時保持正確。
關於壓縮實作的指導與安全考量,請參見 ASP.NET Core 中的回應壓縮。
支援大型資源的部分下載。
如果 API 支援部分下載大型資源,請用 Accept-Ranges來宣傳這項功能。 處理 HEAD 請求時,回傳資源的中繼資料,包括其總長度 Content-Length,且不包含回應主體。 對於指定支援位元組範圍的 GET 請求,回傳 206(部分內容)、回傳部分的 Content-Length,以及識別該資源部分的 Content-Range。 此回應合約允許呼叫者擷取資源的部分內容,而無需 API 回傳整個物件。
在 API 設計中會更詳細地描述 HTTP HEAD 要求和部分回應。
處理大型上傳的 100-Continue
對於大型 HTTP/1.1 上傳,客戶端可以發送帶有 Expect: 100-continue 的請求標頭,並在傳送主體前等待。 伺服器可以發送一個中間的 100(繼續)回應,或在未收到完整內容前拒絕請求。 這次交換是單一請求的一部分,而不是先做一個空請求再接著第二個完整的請求。
配置並測試主機堆疊與閘道器如何處理有無 Expect: 100-continue的請求。 驗證 API 在接受或拒絕上傳時的行為,並衡量對伺服器資源使用與請求延遲的影響。
支援可能返回大量物件的請求分頁功能
擷取整個大型集合可能會增加伺服器處理、網路流量及延遲。
在伺服器上驗證分頁輸入並強制執行最大頁面大小。 以下控制器說明請求驗證。 預設為 10 個結果,並拒絕 1 到 100 以外的 limit 值,或 0 到 10,000 以外的偏移量。 這些界限僅供說明。 根據工作負載和負載測試來選擇限制。 當你使用 [ApiController]時,驗證失敗會產生 400 的回應。 欲了解更多資訊,請參閱使用 ASP.NET Core 建立網頁 API。
using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Authorize]
[Route("orders")]
public sealed class OrderCollectionsController(IOrderRepository repository) : ControllerBase
{
[HttpGet]
public async Task<ActionResult<IReadOnlyList<Order>>> GetOrders(
[FromQuery, Range(1, 100)] int limit = 10,
[FromQuery, Range(0, 10000)] int offset = 0,
CancellationToken cancellationToken = default)
{
var orders = await repository.ListAuthorizedAsync(limit, offset, User, cancellationToken);
return Ok(orders);
}
}
客戶端可透過使用 https://api.contoso.com/orders?limit=30&offset=50從偏移 50 開始請求 30 筆訂單。
除了前述範例所示的請求驗證外,應在回應合約中加入下一頁連結或接續權杖。 例如,回傳訂單時,在有其他頁面可用時,將 nextLink 屬性設為 https://api.contoso.com/orders?limit=30&offset=80。 連結中保留篩選器、排序順序和 API 版本。 省略 nextLink 或在最後一頁設為 null。 關於下一連結合約的範例,請參見 Microsoft Graph 分頁。
在資料存放區中應用篩選和分頁,而不是在載入整個收藏後再做。 使用確定性排序順序。 對於大型或頻繁變動的集合,請評估游標分頁,以避免昂貴的偏移量與不穩定的頁面邊界。
提示
強制執行查詢複雜度、過濾器表達式及請求大小的文件化限制。 測試請求路徑中每個閘道器、代理和伺服器的限制。
維持回應性、可擴展性和可用性
定義 API 關鍵操作的延遲、吞吐量與可用性目標。 設計並測試預期流量、突發流量與相依項故障。 橫向擴充與無狀態處理有助於達成這些目標。 請考慮以下實施需求。
為耗時較長的請求提供非同步支援
對於比一般 HTTP 請求更久的工作,驗證並授權該請求,將工作可靠地記錄下來,並回傳 202(已接受)。 不要指望一個未追蹤的進行中任務在回應後完成:應用程式重啟、縮減和部署都可能中斷它。 當工作必須在即使發生這些事件的情況下仍持續執行時,使用持久佇列與工作者,或是持久工作流程。 欲了解完整的 HTTP 語意與實作指引,請參閱 非同步 Request-Reply 模式。
提供呼叫者取得操作狀態與結果的方法。 API 也能在處理完成時通知呼叫者。
你可以提供一個狀態資源,讓客戶輪詢:
- 客戶提交要求。 在接受工作前,先驗證其輸入與權限。
- 在持久儲存中持續保存操作識別碼與狀態,例如 Azure 資料表儲存體,並為獨立處理器排隊工作,例如使用 Azure 服務匯流排。 協調持久化與加入佇列,確保在這兩個動作之間發生故障時,不會導致已接受的工作遺失。
- 回傳 202,並使用
Location標頭來識別狀態端點,使用Retry-After標頭來控制輪詢頻率。 只有在工作被永久記錄後,才接受請求。 - 工作程序處理作業並更新其持久化狀態。 使處理具有冪等性,因為工作程序可能多次接收相同的工作。 對暫時性失敗限制重試次數。
- 用戶端會輪詢狀態端點。 在狀態端點與結果端點上強制執行資源層級授權。 無法猜測的識別碼不代表授權。
- 在工作進行中傳回有文件的狀態表示。 完成後,提供結果或 303(See Other)重新導向到某個結果資源。 透過一致且安全的錯誤處理契約回報失敗。
- 定義作業記錄與結果的保留與清理。 文件作業過期、重複提交,以及任何支援的取消行為。
對於連接的用戶端,可以考慮使用 ASP.NET Core SignalR 來提供完成通知。 保持持久狀態資源可用,讓客戶端在斷線或錯過通知後能恢復。 欲了解更多資訊,請參閱 ASP.NET Core SignalR 概述。
確保每個請求都是無狀態的
不要要求後續請求必須到達與先前請求相同的應用程式實例。 將工作流程和資源狀態保存在適當的共享儲存庫中,而非僅存於程序記憶體中。 請求可以依賴於持久資源狀態,而不會產生對伺服器執行個體的親和性。 無狀態的請求處理支援橫向擴充。
了解下游相依性
為每次下游呼叫設定一個逾時。 將呼叫、重試與延遲的總時間控制在 API 請求的期限內,並將請求取消傳遞至下游作業。
只重試因暫時性故障而失敗且可安全重複的操作。 採用有界重試,並搭配退避與抖動。 限制每個相依項的總重試次數,以及每個請求的嘗試次數。 如需詳細資訊,請參閱處理暫時性錯誤。
當反覆的相依性失效可能耗盡 API 容量時,應使用 斷路器 。
追蹤用戶端並實施節流以降低 DoS 攻擊的可能性
套用請求率、並行性、承載資料及執行時間限制。 盡可能依已驗證的呼叫者或租用戶劃分限制。 當呼叫端超過設定速率時,回傳 429(請求過多),暫時無法使用則回傳 503(服務不可用)。 請在適當情況下加入 Retry-After。 如果 API 重試呼叫下游相依項目,請限制這些重試次數,避免加劇過載。
閘道器限制與應用程式限制有不同的用途。 閘道限制可以保護共享容量。 應用限制可反映營運成本及下游容量。 兩者都無法取代網路層的 DDoS 防護或網頁應用防火牆。 如需詳細資訊,請參閱 節流模式。
謹慎管理永久 HTTP 連線
對於入站連線,設定伺服器與閘道保持活絡逾時、請求逾時,以及工作負載與網路路徑的同時連線限制。 不要每次回應後就強迫連線結束。 關於 ASP.NET Core 伺服器設定的資訊,請參閱 Kestrel 網頁伺服器的配置選項。
如果 API 本身呼叫下游 HTTP 服務,請重用那些出站連線。 在 .NET API 實作中,使用具有適當 HttpClient 的長期存留 PooledConnectionLifetime 執行個體,或使用由 IHttpClientFactory 建立的用戶端。 當外發回應訊息和串流不再需要時,請將其釋放。 這些設定適用於 API 的下游呼叫,而非傳入的用戶端連線。 關於細節及 Cookie 處理的注意事項,請參閱 使用 HttpClient 的指引。
發佈和管理 Web API
將 API 部署到符合其營運需求的主機環境。 請考慮下列策略:
- 使用 HTTPS。 驗證受保護端點的請求,並強制執行每個資源與操作的授權。
- 隨著需求變化,擴展主機環境以滿足回應時間承諾。
- 如果 API 的計費模式需要,則請求 Meter。
- 管制流量並在需要時執行客戶配額。
- 記錄合規與事件回應所需的稽核事件,但不要記錄憑證、令牌或敏感的請求與回應主體。
- 監控主機健康狀況並定義復原行動,例如重新啟動不健康的主機。
考慮使用一個獨立的門面,處理共享管理問題並將驗證後的請求轉發給 API。 立面可以提供以下功能:
- 作為多個 Web API 的整合點。
- 轉換訊息和翻譯通訊協定,以適應使用不同技術建置的用戶端。
- 快取請求和回應,以減少對托管 Web API 伺服器的負載。
將 API 合約與閘道設定納入版本控制,在部署管線中驗證這些變更,並定義回滾程序。 將託管、身分識別、網路與治理與組織的登陸區方法對齊。 如需詳細資訊,請參閱 什麼是 Azure 登陸區域?。
測試 Web API
使用單元測試來驗證 API 的邏輯,並用整合測試來驗證其 HTTP 行為。
請包含以下檢查項目:
測試所有路由,以確認其是否叫用正確的操作。 特別要注意 HTTP 狀態碼 405(方法不允許)會意外回傳。 此狀態碼可能表示路由與可派遣至該路由的 HTTP 方法(GET、POST、PUT、DELETE)不符。
發送使用各路由不支援方法的請求,並驗證文件中記錄的 405(方法不允許)回應與
Allow標頭。確認所有路由是否得到適當的保護,並經過適當的驗證和授權檢查。
註記
某些安全面向,例如使用者驗證,通常由主機環境負責,而非網頁 API,但部署過程中仍需包含安全測試。
測試每個作業執行的例外狀況處理,並確認是否將適當且有意義的 HTTP 回應傳回給用戶端應用程式。
確認請求和回應訊息的格式是否正確。 例如,對於建立資源的 POST 請求,請驗證反序列化、解析、資源建立以及回應的
Location標頭。將支援與不支援的請求媒體類型測試,與回應內容協商分開進行。 請驗證 415(不支援的媒體類型)回應,針對不支援的請求格式,以及文件中對格式錯誤的要求主體的驗證錯誤。
測試所有支援的 API 版本,包括其路由、請求驗證及回應架構。 測試遺漏、格式錯誤及不支援的版本識別碼,並驗證快取回應不會跨越版本邊界。
確認回應訊息中的所有連結和 URI。 例如,HTTP POST 訊息應該會傳回新建立資源的 URI。 所有 HATEOAS 連結都應該有效。
確認每個作業都會針對不同的輸入組合傳回正確的狀態碼。 例如:
- 如果查詢成功,應該會回傳狀態代碼 200(OK)。
- 如果找不到資源,作業應該會傳回 HTTP 狀態碼 404 (找不到)。
- 如果用戶端傳送的請求成功刪除了資源,狀態碼應為 204 (沒有內容)。
- 如果用戶端傳送的請求建立了一個新資源,狀態碼應為 201 (已建立)。
調查來自應用程式或主機層的意外 5xx 回應。
測試用戶端應用程式可以指定的不同請求標頭組合,並確保 Web API 在回應訊息中傳回預期的資訊。
測試查詢字串。 如果操作可以接受可選參數(例如分頁請求),則測試不同組合及參數的順序。
確認非同步作業是否成功完成。 對於串流回應,請確認 API 沒有緩衝整個有效載荷,並正確處理客戶端斷線與取消。 如果 API 提供長期執行作業的狀態資源,請確認它們是否正確回報作業進度與結果。
測試影響正確性的失效與邊界情況:
- 驗證最小、最大、負值、畸形及過多分頁與批次輸入。
- 請透過分頁連結一直前往最後一頁。 確認連結是否保留查詢選項,且文件記載的完成訊號是否被回傳。
- 確認額外的輸入欄位無法改變受保護的屬性,且欄位選擇不會暴露未經授權的資料。
- 測試匹配、非匹配、弱、多重及百搭符 ETag,並驗證 304 回應是否不含任何回應本文。
- 同時進行更新,並確認資料儲存會以原子方式拒絕過時寫入。
- 確認來電者無法讀取其他來電者的資源、狀態紀錄或快取回應。
- 多租戶 API 則測試偽造或不匹配的租戶識別碼。 啟用快取時,測試是否有來自不同租戶、針對同一資源 URI 的請求。
- 模擬逾時、客戶端取消、相依性失敗、工作者重啟,以及背景工作的重複交付。
- 確認下游逾時與重試預算、取消及斷路器恢復。
- 確認 429(請求過多)和 503(服務無法使用)回應、重試行為,以及拒絕過載請求的成本。
針對類似生產環境的基礎設施和現實操作組合進行負載測試。 定義吞吐量、延遲百分位、錯誤率及資源飽和度的通過與失敗標準。 使用 Azure 負載測試,並將回歸檢查整合進部署流程。
使用 API 管理
當你需要一個具有原則強制執行功能的受控閘道時,可以考慮使用 Azure API 管理。 這會增加成本、另一個網路跳躍,以及請求路徑的依賴性。 根據容量、網路、可用性及區域需求選擇服務層級與拓撲;功能會依等級而異。 開發者層級並非為生產工作負載設計。 請遵循 API 管理的 Well-Architected 服務指引。
您可以透過以下步驟發布和管理網頁 API:
將 web API 部署到託管平台,例如 Azure App 服務、Azure 容器應用程式、Azure Kubernetes Service (AKS) 或 Azure 虛擬機器。
設定 API 管理,將來自其閘道 URL 的要求路由到後端 API。 一個 API Management 實例可以將請求路由到多個 API。 當應用程式需要不同的存取邊界時,多個實例也可能暴露相同的後端 API。
註記
回應中的 HATEOAS 連結應指向 API 管理閘道 URL,而非後端伺服器 URL。
匯入版本控制的 OpenAPI 定義,並驗證匯入的操作、參數、安全需求及回應架構是否符合實作。 請檢查支援的 OpenAPI 版本及匯入限制。 欲了解更多資訊,請參閱 匯入 OpenAPI 規範。
為用戶端至閘道及閘道至後端通訊配置認證與授權。 驗證 OAuth 2.0 存取權杖,並強制執行客戶端請求所需的權限。 對於支援 Microsoft Entra ID 認證的後端,建議使用僅具備所需權限的 API Management 管理身份。 憑證認證也是另一個選項。 當有更安全的選項時,避免使用基本認證。 欲了解更多資訊,請參閱 Azure API 管理 中的 API 認證與授權。
註記
如果你需要 API Management 訂閱金鑰,請不要用它們來取代認證和資源層級授權。
根據需要設定驗證、跨來源存取、訊息轉換、IP 過濾、速率限制及配額等政策。 只設定回應快取,只針對可安全快取的資料。 在適當範圍內套用政策,並驗證其在每次操作中的有效行為。
如需詳細資訊,請參閱 API 管理檔。
Important
閘道器不會讓後端成為私有,也不會取代資源層級授權。 設計後端存取控制、故障處理、容量與可觀測性,涵蓋整體負載,包括閘道器。 評估可用區與區域冗餘,並依據所選層級的能力進行評估。 成本模型中應包含閘道費用、遙測資料擷取與保留,以及資料傳輸。
支援用戶端開發人員
為 API 使用者提供有關認證、操作、參數、資料型態及回應碼的文件。
記錄 Web API 的 REST 作業
發布一個 OpenAPI 定義,描述該 API 的操作、參數、請求與回應架構,以及安全要求。 將其與實作一同納入版本控制,並確認它是否符合 API 的實際行為。
補充 API 參考,說明使用者需要正確使用 API 的指引:
- 每個操作的認證要求與權限。
- 代表性請求、成功回應及錯誤回應。
- 輸入驗證規則、承載資料限制、分頁與速率限制。
- 逾時行為、重試安全,以及任何冪等性要求。
- 長時間執行的作業之狀態與結果檢索。
- 版本控制與相容性期望。
當 API 合約變更時,請更新文件和範例。
實作用戶端 SDK
考慮為 API 使用者提供 SDK。 SDK 可以公開型別化的方法,用來構造請求、解析回應,並顯示 API 已記錄的錯誤。
考慮從 API 的 OpenAPI 定義中產生型別化用戶端,但要根據該服務驗證所產生的行為。 文件驗證、逾時、取消、分頁、錯誤回應,以及哪些操作可安全重試。 保持用戶端與 API 相容性政策一致。 產生的程式碼並不會消除整合測試的需求。
監控網頁 API
同時監控 API、其相依關係以及任何閘道器。 根據客戶影響定義服務層級目標與警示,而非僅依賴主機健康狀況。
直接監控 Web API
使用 OpenTelemetry 檢測收集追蹤、指標與日誌,並將訊號匯出至 Application Insights 或其他支援的後端。 關於 .NET、Node.js 和 Python 檢測,請遵循 Microsoft OpenTelemetry Distro 的指引。 Java 使用 Azure 監視器 OpenTelemetry Distro。 請遵循特定語言的 OpenTelemetry 啟用指引。
描述 API 行為的監測訊號:
- 按操作分類的請求量、失敗率與延遲百分位數
- 相依性延遲、失敗與逾時
- 速率限制拒絕、並行作業與資源飽和
- 背景操作佇列年齡、完成時間、失敗與重試
- 快取效能,當快取是設計的一部分時
監控工具自動收集的遙測數據會依語言、函式庫及設定而異。 新增用於網域作業和背景工作的監測。 不要假設瀏覽器工作階段、使用者角色或所有請求詳細資料都會自動提供。 在閘道、應用程式和工作者之間傳播追蹤上下文。 配置取樣與保留,以平衡診斷需求、資料敏感度與遙測成本。
在適當情況下,使用 Application Insights 標準可用性測試 來進行定期外部檢查。 檢查有意義的健康或操作端點,同時不暴露敏感資料,定義可執行的警示,並維護回應執行手冊。
透過使用 API Management 監視 Web API
利用 API Management 支援的 Azure 監視器 指標、日誌、分析和診斷,來區分閘道失敗與後端故障。 關聯閘道與應用程式遙測,監控政策失效、容量、請求延遲及限速。 可用訊號依據層級與閘道器配置而定。
請遵循 API 管理的 Well-Architected 服務指引中的可觀察性與容量建議。
下一步
- ASP.NET Core OData 概述說明如何使用 ASP.NET Core 建立符合 OData 協定的 REST API 服務。
- ASP.NET Core 最佳實務涵蓋非同步 I/O、資源使用與回應處理。
- 冪等消費者模式 提供實作指引,用於追蹤已處理的訊息 ID 及處理重複投遞。
- HTTP 語意 定義 HTTP 狀態碼。
- 非同步 Request-Reply 模式 描述了持久的背景工作與狀態資源。
- Azure API 管理 的架構最佳實務涵蓋可靠性、安全性、成本、營運與效能。
- Azure 負載測試 說明負載產生與自動化效能檢查。
- 啟用 OpenTelemetry 提供語言專屬的插樁與匯出指引。