ASP.NET Web API 的核心是一個訊息處理管道,由一組有序的 HttpMessageHandler 串聯而成。這個雙工管道讓請求訊息從一端流入,依序經過各 Handler 處理,抵達 HttpControllerDispatcher 激活 Controller 執行 Action,響應訊息再逆向流經管道返回客戶端。這種設計賦予 Web API 高度可擴展性與彈性。
定義於 System.Net.Http 命名空間,為抽象基類:
public abstract class HttpMessageHandler : IDisposable
{
public void Dispose();
protected virtual void Dispose(bool disposing);
protected abstract Task<HttpResponseMessage> SendAsync(
HttpRequestMessage request, CancellationToken cancellationToken);
}
SendAsync:非同步處理核心。請求處理直接在方法內實作;響應處理透過回傳的 Task<HttpResponseMessage> 完成(續行任務)。IDisposable 標準模式,衍生類別可覆寫 Dispose(bool) 釋放資源。繼承 HttpMessageHandler,持有 InnerHandler 參考,形成委派鏈:
public abstract class DelegatingHandler : HttpMessageHandler
{
public HttpMessageHandler InnerHandler { get; set; }
protected internal override Task<HttpResponseMessage> SendAsync(
HttpRequestMessage request, CancellationToken cancellationToken);
}
管道結構示意:
HttpServer (Head)
-> DelegatingHandler1 (MessageHandlers[0])
-> DelegatingHandler2 (MessageHandlers[1])
-> ...
-> HttpRoutingDispatcher / HttpControllerDispatcher (Tail)
定義於 System.Web.Http,繼承 DelegatingHandler:
public class HttpServer : DelegatingHandler
{
public HttpConfiguration Configuration { get; }
public HttpMessageHandler Dispatcher { get; } // 管道尾端
public HttpServer();
public HttpServer(HttpMessageHandler dispatcher);
public HttpServer(HttpConfiguration configuration);
public HttpServer(HttpConfiguration configuration, HttpMessageHandler dispatcher);
protected override void Dispose(bool disposing);
protected virtual void Initialize();
protected override Task<HttpResponseMessage> SendAsync(...);
}
Configuration:管道設定物件,含 MessageHandlers 集合。Dispatcher:管道尾端 Handler,預設為 HttpRoutingDispatcher。HttpConfiguration 與 HttpRoutingDispatcher。管道尾端預設 Handler,負責:
IHttpRouteHttpControllerDescriptor 與 HttpActionDescriptorHttpControllerDispatcherHttpControllerContextIHttpControllerActivator 建立 Controller 實例IHttpActionInvoker 執行 Action 方法HttpResponseMessage 回傳管道在 WebApiConfig.cs 中加入自訂 Handler:
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
// 註冊順序 = 管道順序(由外而內)
config.MessageHandlers.Add(new CustomLoggingHandler());
config.MessageHandlers.Add(new ApiKeyAuthenticationHandler());
config.MessageHandlers.Add(new CompressionHandler());
// 其他路由設定...
}
}
public class CustomLoggingHandler : DelegatingHandler
{
protected override async Task<HttpResponseMessage> SendAsync(
HttpRequestMessage request, CancellationToken cancellationToken)
{
// 請求前處理
var requestBody = await request.Content.ReadAsStringAsync();
Log.Info($"Request: {request.Method} {request.RequestUri} {requestBody}");
// 呼叫內層 Handler (傳遞請求)
var response = await base.SendAsync(request, cancellationToken);
// 響應後處理
var responseBody = await response.Content.ReadAsStringAsync();
Log.Info($"Response: {response.StatusCode} {responseBody}");
return response;
}
}
Request -> [Handler1] -> [Handler2] -> ... -> [ControllerDispatcher] -> Controller.Action
|
Response <- [Handler1] <- [Handler2] <- ... <- [ControllerDispatcher] <- HttpResponseMessage
Task/await,高併發下不阻塞執行緒。深入理解管道機制,是掌握 Web API 擴展點、實作跨領域關注點(Cross-cutting Concerns)的基礎。