ASP.NET Web API标准的“管道式”设计

ASP.NET Web API的核心框架是一个消息处理管道，这个管道是一组HttpMessageHandler的有序组合。这是一个双工管道，请求消息从一端流入并依次经过所有HttpMessageHandler的处理。在另一端，目标HttpController被激活，Action方法被执行，响应消息随之被生成。响应消息逆向流入此管道，同样会经过逐个HttpMessageHandler的处理。这是一个独立于寄宿环境的抽象管道，如何实现对请求的监听与接收，以及将接收的请求传入消息处理管道进行处理并将管道生成的响应通过网络回传给客户端，这就是Web API寄宿需要解决的问题。[本文已经同步到《How ASP.NET Web API Works?》]

目录
一、HttpMessageHandler
二、DelegatingHandler
三、HttpServer
四、HttpRoutingDispatcher
五、HttpControllerDispatcher

一、HttpMessageHandler

ASP.NET Web API的消息处理管道由一组HttpMessageHandler经过“首尾相连”而成，ASP.NET Web API之所以具有较高的可扩展性，主要源于采用的管道式设计。虽然ASP.NET Web API框架旨在实现针对请求的处理和响应的回复，但是采用的处理策略因具体的场景而不同。

我们不可能也没有必要创建一个“万能”的处理器来满足所有的请求处理需求，倒不如让某个处理器只负责某个单一的消息处理功能。在具体的应用场景中，我们可以根据具体的消息处理需求来选择所需的处理器并组成一个完整的消息处理管道。在这里这个用于完成某个单一消息处理功能的处理器就是HttpMessageHandler。

这里的“消息处理”具有两个层面的含义，既包括针对请求消息的处理，还包括针对响应消息的处理。HttpMessageHandler直接或者间接继承自具有如下定义的抽象类型HttpMessageHandler，该类型定义在命名空间“System.Net.Http”下。ASP.NET Web API通过类型HttpRequestMessage和HttpResponseMessage来表示管道处理的请求消息和响应消息，所以对HttpMessageHandler的定义就很好理解了。

public abstract class HttpMessageHandler : IDisposable
{
    public void Dispose();
    protected virtual void Dispose(bool disposing);
    protected abstract Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken);
}

如上面的代码片断所示，抽象类HttpMessageHandler定义了一个受保护的抽象方法SendAsync，这是一个采用针对Task的“并行编程模式”的异步方法，在后续的章节中我们会看到ASP.NET Web API的应用程序接口基本上都采用这样的定义方式。对于这个SendAsync方法来说，request参数表示传递给当前HttpMessageHandler进行处理的请求，这是一个HttpRequestMessage对象。另一个参数cancellationToken是一个用于发送取消操作信号的CancellationToken对象，如果读者对.NET中的并行编程具有基本了解的话，相信对这个类型不会感到陌生。

针对请求消息和响应消息的处理均体现在这个SendAsync方法上。具体来说，针对请求消息的处理直接实现在SendAsync方法中，而针对响应消息的处理则通过其返回的Task<HttpResponseMessage>对象来完成。由HttpMessageHandler组成的消息处理管道以及请求消息和响应消息在管道中的“流动”基本上可以通过右图来体现。

抽象类HttpMessageHandler实现了IDisposable接口，它按照“标准”的方式实现Dispose方法。如下面的代码片断所示，当我们调用Dispose方法的时候，HttpMessageHandler并没有执行任何资源回收操作。当我们通过继承这个抽象类自定义HttpMessagHandler的时候，可以将资源回收操作实现在重写的Dispose方法中。

public abstract class HttpMessageHandler : IDisposable
{
    //其他操作
    public void Dispose()
    {
        this.Dispose(true);
        GC.SuppressFinalize(this);
    }

    protected virtual void Dispose(bool disposing)
    {}
}

二、DelegatingHandler

我们说ASP.NET Web API消息处理管道是通过一组有序的HttpMessagHandler“首尾相连”而成，具体实现“管道串联”是通过DelegatingHandler这个类型来完成的。顾名思义，DelegatingHandler具有委托功能，当它自己负责的消息处理任务完成之后可以委托另一个HttpMessagHandler进行后续的处理。如果这个被委托的也是一个DelegatingHandler对象，不就可以组成一个委托链了吗？而这个委托链不就是由一个个DelegatingHandler组成的消息处理管道吗？

如下面的代码片断所示，DelegatingHandler是一个继承自HttpMessageHandler类的抽象类。上面我们所说的这个被委托的HttpMessagHandler由它的属性InnerHandler表示。DelegatingHandler重写了定义在其类的抽象方法SendAsync来调用InnerHandler属性的同名方法。

public abstract class DelegatingHandler : HttpMessageHandler
{
    protected internal override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken);
    public HttpMessageHandler InnerHandler get;  set; }
}

正如上面所说，如果ASP.NET Web API的消息处理管道均由DelegatingHandler组成（位于管道尾端的HttpMessageHandler除外），我们就可以根据其InnerHandler获得对被委托的HttpMessageHandler对象的引用，由此便构成具有如上图所示的链式结构。组成ASP.NET Web API核心框架的消息处理管道就这么简单。

三、HttpServer

一般来说，对于构成ASP.NET Web API消息处理管道的所有HttpMessageHandler来说，除了处于尾端的那一个之外，其余的均为DelegatingHandler，那么通过InnerHandler属性维持着“下一个” HttpMessageHandler。作为这个HttpMessageHandler链“龙头”的是一个HttpServer对象，该类型定义在命名空间“System.Web.Http”下。

如下面的代码片断所示，HttpServer直接继承自DelegatingHandler。它具有两个重要的只读属性（Configuration和Dispatcher），我们可以通过前者得到用于配置整个消息处理管道的HttpConfiguration对象，另外一个属性Dispatcher返回的是处于整个消息处理管道“尾端”的HttpMessageHandler。

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(HttpRequestMessage request, CancellationToken cancellationToken);
}

HttpServer的Configuration和Dispatcher属性均可以在相应的构造函数中初始化。如果在构造HttpServer的时候没有显式指定这两个属性的值（调用默认的无参构造函数创建HttpServer），在默认情况下会创建一个HttpConfiguration作为Configuration的属性值，而作为Dispatcher属性值的则是一个HttpRoutingDispatcher对象，该类型定义在命名空间“System.Web.Http.Dispatcher”下。除此之外。由于HttpConfiguration类型实现了IDisposable接口，所以HttpServer重写了虚方法Dispose并在该方法中完成了对HttpConfiguration对象的释放。

当HttpServer对象被成功创建之后，对应的消息处理管道的“一头一尾”已经确定下来。一头指的就是HttpServer对象本身，一尾指的自然就是通过Dispatcher属性引用的HttpMessageHandler对象了。ASP.NET Web API框架最大的扩展性就在于我们可以根据具体的消息处理需求来“定制”这个消息处理管道，它允许我们将自定义的HttpMessageHandler按照如左图所示的方式“安装”到这一头一尾之间，但是这些处于“中间位置”的HttpMessageHandler是如何注册呢？

既然整个管道都是由HttpConfiguration进行配置，那么自定义HttpMessageHandler的注册自然也可以利用它来完成。如下面的代码片断所示，HttpConfiguration具有一个只读的集合类型的MessageHandlers，需要注册的HttpMessageHandler需要添加到此集合之中。由于这是一个元素类型为DelegatingHandler的集合，所以我们自定义的HttpMessageHandler必须继承自DelegatingHandler。

public class HttpConfiguration : IDisposable
{
    //其他成员
    public Collection<DelegatingHandler> MessageHandlers { get; }
}

通过上面的给出的HttpServer类型定义我们可以看到它具有一个受保护的Initialize方法，该方法最终完成了对整个消息处理管道的构建。在重写的SendAsync方法中，如果自身尚未被初始化，该Initialize方法会自动被调用以确保整个消息处理管道已经被成功构建。

四、HttpRoutingDispatcher

在默认情况下，作为消息处理管道“龙头”的HttpServer的Dispatcher属性返回一个HttpRoutingDispatcher对象，它可以视为这个消息处理管道的最后一个HttpMessageHandler。Web API调用请求一般都是针对定义在某个HttpController中的某个Action方法，所以消息处理管道最终需要激活相应的HttpController并执行对应的Action方法，HttpRoutingDispatcher完成了目标HttpController的激活和Action方法的执行。

如下面的代码片断所示，HttpRoutingDispatcher不再是DelegatingHandler的继承者，它的直接基类是抽象类HttpMessageHandler。我们在构建一个HttpRoutingDispatcher对象的时候需要指定一个HttpConfiguration对象，而通过参数defaultHandler指定的HttpMessageHandler对于创建的HttpRoutingDispatcher对象来说具有重要的意义，因为HttpController的激活、Action方法的选择与执行等后续操作实际上是由它来完成的。

public class HttpRoutingDispatcher : HttpMessageHandler
{
    public HttpRoutingDispatcher(HttpConfiguration configuration);
    public HttpRoutingDispatcher(HttpConfiguration configuration, HttpMessageHandler defaultHandler);

    protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken);
}

虽然ASP.NET Web API消息处理管道不具有一个类似于HttpContext的对象来保存基于当前请求的上下文信息，但是表示请求消息的HttpRequestMessage对象具有一个通过Properties属性表示的属性字典，我们可以利用它来作为上下文数据的存放容器。

通过上面对HttpServer的介绍我们知道它会将当前SynchronizationContext和HttpConfiguration添加到表示当前请求的HttpRequestMessage对象的属性字典中。与之类似，通过路由系统生成的HttpRouteData也以同样的方式保存在HttpRequestMessage的属性字典之中，我们可以直接调用HttpRequestMessage的如下两个扩展方法GetRouteData和SetRouteData进行HttpRouteData的获取和设置。

public static class HttpRequestMessageExtensions
{
    //其他成员
    public static IHttpRouteData GetRouteData(this HttpRequestMessage request);
    public static void SetRouteData(this HttpRequestMessage request, IHttpRouteData routeData);
}

HttpRoutingDispatcher的SendAsync方法被执行时，它会判断作为参数的HttpRequestMessage对象的属性字典中是否具有这样一个HttpRouteData对象。如果此HttpRouteData对象存在，它会直接将请求交付给创建时指定的HttpMessageHandler进行处理。这样的情况会发生在Web Host寄宿模式下。

如果封装路由数据的HttpRouteData对象尚未添加到表示被处理请求的HttpRequestMessage对象的属性字典中，意味着针对请求的路由尚未发生，这种情况会发生在Self Host寄宿模式下。在这种情况下，HttpRoutingDispatcher会直接通过当前HttpConfiguration的Routes属性得到全局路由表，并将HttpRequestMessage对象作为参数调用其GetRouteData方法以实现针对当前请求的路由解析。

如果执行路由表的GetRouteData方法返回一个具体的HttpRouteData对象，意味着当前请求与注册的某个HttpRoute相匹配，HttpRoutingDispatcher会将这个HttpRouteData对象添加到HttpRequestMessage对象的属性字典中。在这之后，ASP.NET Web API会将请求交付给创建时指定的HttpMessageHandler进行后续处理。如果执行GetRouteData方法返回Null，意味着当前请求与注册的路由规则不匹配，客户端会得到一个状态为“404， Not Found”的响应。

五、HttpControllerDispatcher

我们从类型命名可以看出HttpRoutingDispatcher具有两个基本的职能，即“路由（Routing）”和“消息分发（Dispatching）”。对于前者，它会调用当前路由表对请求消息实施路由解析进而生成用于封装路由数据的HttpRouteData（如果这样的HttpRouteData不存在于当前请求的属性字典中）。对于后者，它会将请求直接分发给在创建时指定的HttpMessageHandler来完成进一步处理。

如果在构建HttpRoutingDispatcher对象的时候没有通过参数defaultHandler显式指定这么一个HttpMessageHandler对象，默认情况下从它手中接管请求的HttpMessageHandler是一个具有如下定义的HttpControllerDispatcher的对象，该类型定义在命名空间“System.Web.Http.Dispatcher”下。HttpControllerDispatcher在整个消息处理管道中显得尤为重要，因为目标HttpController的激活、Action方法的执行和响应生成均是由HttpControllerDispatcher来完成的。

public class HttpControllerDispatcher : HttpMessageHandler
{
    public HttpControllerDispatcher(HttpConfiguration configuration);
    protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken);

    public HttpConfiguration Configuration { get; }
}

在我们引入HttpControllerDispatcher对象之后，ASP.NET Web API的消息处理管道将具有如右图所示的结构。从这个结构来看，貌似HttpControllerDispatcher才是整个消息处理管道的最后一个HttpMessageHandler。这种说法没有错，但我个人还是倾向于将HttpControllerDispatcher视为“隶属于” HttpRoutingDispatcher的“内部”HttpMessageHandler，所以仍将这个“包含” HttpControllerDispatcher的HttpRoutingDispatcher视为组成消息处理管道的最后一个HttpMessageHandler。

除此之外，“N个DelegagingHandler + 1个HttpMessageHander”这样的链式结构也刚好与基于DelegagingHandler的委托链相匹配。对于读者朋友来说，具体倾向于哪种说法并不重要，重要的是能够深刻了解整个消息处理管道的是如何构成的。