走进WebApiClientCore的设计

WebApiClient

WebApiClient是NCC开源社区的一个项目，是目前微服务里http接口调用的一把锋利尖刀，项目早期设计与开发的时候，是基于.netframework的，然后慢慢加入netstandard和netcoreapp多个框架的支持，设计能力出众，AOP能力唾手可得易如反掌。

WebApiClientCore

WebApiClient很优秀，它将不同框架不同平台都实现了统一的api；WebApiClient不够优秀，它在.netcore下完全可以更好，但它不得不兼容.net45开始所有框架而有所牺牲。所以WebApiClientCore横空出世，它是WebApiClient.JIT的.netcore替代版本，目前尚属于alpha阶段，计划只支持.netcore平台，并紧密与.netcore新特性紧密结合。

WebApiClientCore的变化

• 使用System.Text.Json替换Json.net，提升序列化性能

• 移除HttpApiFactory和HttApiConfig功能，使用Microsoft.Extensions.Http的HttpClientFactory

• 移除AOT功能，仅保留依赖于Emit的运行时代理

• 高效的ActionInvoker，对返回Task<>和ITask<>作不同处理

• 所有特性都都变成中间件，基于管道编排各个特性并生成Action执行委托

• 良好设计的HttpContext、ApiRequestContext、ApiParameterContext和ApiResponseContext

WebApiClientCore执行流程设计

1 接口代理类生成设计

Cretate<THttpApi>() -> BuildProxyType() -> CreateProxyInstance(ActionInterceptor)

1.1 HttpApiProxyTypeBuilder

在HttpApi.Create()时，先调用HttpApiProxyTypeBuilder来生成THttpApi接口的代理类，HttpApiProxyTypeBuilder是基于Emit方案，Build出来的代理类在每个方法调用时触发一次拦截器ActionInterceptor的Intercept()方法，将调用参数传给拦截器。

1.2 HttpApiProxyBuilder

给定一个代理类的类型(Type)，快速生成代理类的实例，这个Builder实际是生成并保存了代理类构造器的高效调用委托，属于反射优化。

2 ActionInterceptor的设计

ActionInterceptor.Intercept(MethodInfo) -> CreateActionInvoker() -> ActionInvoker.Invoke()

ActionInterceptor在拦截到方法调用时，根据方法的MethodInfo信息，创建ActionInvoker，然后调用ActionInvoker.Invoke()执行。当然，ActionInvoker并不是总是创建的，因为它的创建是有成本的，ActionInterceptor使用了缓存ActionInvoker的方案。

2.1 MultiplexedActionInvoker

WebApiClientCore支持加Task<>和ITask<>两种异步声明，MultiplexedActionInvoker实际上包装了ActionInvoker和ActionTask两个字段，当声明为Task<>时，调用ActionInvoker执行，当声明为ITask<>是，返回创建实现了ITask<>接口的ActionTask实例。

2.2 ActionInvoker

ActionInvoker是一个ApiActionDescriptor的执行器，其实现了IActionInvoker.Invoke(ServiceContext context, object[] arguments)接口。关于Descriptor的设计模式，我们在asp.netcore的各种AtionContext里可以发现，有了ApiActionDescriptor，再给它各个参数值，Action就很容易执行起来了。

3 RequestDelegate生成设计

ActionInvoker在拿到各个参数值之后，并不是直接从ApiActionDescriptor查找各个特性来执行，而是在执行前就把执行流程编译好，得到一个执行委托，这个委托叫RequestDelegate，其原型为Func<ApiRequestContext, Task<ApiResponseContext>> Build(ApiActionDescriptor apiAction)。抽象成传入请求上下文件，返回响应上下文，当真正执行时，调用这个委托即可。如果你熟悉asp.netcore，那么应该很容易理解下面代码的思路：

/// <summary>
/// 提供Action的调用链委托创建
/// </summary>
static class RequestDelegateBuilder
{
/// <summary>
/// 创建执行委托
/// </summary>
/// <returns></returns>
public static Func<ApiRequestContext, Task<ApiResponseContext>> Build(ApiActionDescriptor apiAction)
{
var requestHandler = BuildRequestHandler(apiAction);
var responseHandler = BuildResponseHandler(apiAction);

return async request =>
{
await requestHandler(request).ConfigureAwait(false);
var response = await SendRequestAsync(request).ConfigureAwait(false);
await responseHandler(response).ConfigureAwait(false);
return response;
};
}


/// <summary>
/// 创建请求委托
/// </summary>
/// <param name="apiAction"></param>
/// <returns></returns>
private static InvokeDelegate<ApiRequestContext> BuildRequestHandler(ApiActionDescriptor apiAction)
{
var builder = new PipelineBuilder<ApiRequestContext>();

// 参数验证特性验证和参数模型属性特性验证
builder.Use(next => context =>
{
var validateProperty = context.HttpContext.Options.UseParameterPropertyValidate;
foreach (var parameter in context.ApiAction.Parameters)
{
var parameterValue = context.Arguments[parameter.Index];
ApiValidator.ValidateParameter(parameter, parameterValue, validateProperty);
}
return next(context);
});

// action特性请求前执行
foreach (var attr in apiAction.Attributes)
{
builder.Use(attr.OnRequestAsync);
}

// 参数特性请求前执行
foreach (var parameter in apiAction.Parameters)
{
var index = parameter.Index;
foreach (var attr in parameter.Attributes)
{
builder.Use(async (context, next) =>
{
var ctx = new ApiParameterContext(context, index);
await attr.OnRequestAsync(ctx, next).ConfigureAwait(false);
});
}
}

// Return特性请求前执行
foreach (var @return in apiAction.Return.Attributes)
{
if (@return.Enable == true)
{
builder.Use(@return.OnRequestAsync);
}
}

// Filter请求前执行
foreach (var filter in apiAction.FilterAttributes)
{
if (filter.Enable == true)
{
builder.Use(filter.OnRequestAsync);
}
}

return builder.Build();
}

/// <summary>
/// 创建响应委托
/// </summary>
/// <param name="apiAction"></param>
/// <returns></returns>
private static InvokeDelegate<ApiResponseContext> BuildResponseHandler(ApiActionDescriptor apiAction)
{
var builder = new PipelineBuilder<ApiResponseContext>();

// Return特性请求后执行
foreach (var @return in apiAction.Return.Attributes)
{
if (@return.Enable == false)
{
continue;
}

builder.Use(async (context, next) =>
{
if (context.ResultStatus == ResultStatus.None)
{
await @return.OnResponseAsync(context, next).ConfigureAwait(false);
}
else
{
await next().ConfigureAwait(false);
}
});
}

// 验证Result是否ok
builder.Use(next => context =>
{
try
{
ApiValidator.ValidateReturnValue(context.Result, context.HttpContext.Options.UseReturnValuePropertyValidate);
}
catch (Exception ex)
{
context.Exception = ex;
}
return next(context);
});

// Filter请求后执行
foreach (var filter in apiAction.FilterAttributes)
{
if (filter.Enable == true)
{
builder.Use(filter.OnResponseAsync);
}
}

return builder.Build();
}


/// <summary>
/// 执行http请求
/// </summary>
/// <param name="context"></param>
/// <returns></returns>
private static async Task<ApiResponseContext> SendRequestAsync(ApiRequestContext context)
{
try
{
var apiCache = new ApiCache(context);
var cacheValue = await apiCache.GetAsync().ConfigureAwait(false);

if (cacheValue != null && cacheValue.Value != null)
{
context.HttpContext.ResponseMessage = cacheValue.Value;
}
else
{
using var cancellation = CreateLinkedTokenSource(context);
var response = await context.HttpContext.Client.SendAsync(context.HttpContext.RequestMessage, cancellation.Token).ConfigureAwait(false);

context.HttpContext.ResponseMessage = response;
await apiCache.SetAsync(cacheValue?.Key, response).ConfigureAwait(false);
}
return new ApiResponseContext(context);
}
catch (Exception ex)
{
return new ApiResponseContext(context) { Exception = ex };
}
}

/// <summary>
/// 创建取消令牌源
/// </summary>
/// <param name="context"></param>
/// <returns></returns>
private static CancellationTokenSource CreateLinkedTokenSource(ApiRequestContext context)
{
if (context.CancellationTokens.Count == 0)
{
return CancellationTokenSource.CreateLinkedTokenSource(CancellationToken.None);
}
else
{
var tokens = context.CancellationTokens.ToArray();
return CancellationTokenSource.CreateLinkedTokenSource(tokens);
}
}


}

WebApiClientCore的特性设计

WebApiClientCore的核心特性为以下4种，每种功能各不一样，在设计上使用了中间件的思想，每一步执行都可以获取到context对象和下一个中间件next对象，开发者在实现自定义Attribute时，可以选择性的进行短路设计。

1 IApiActionAttribute

表示Action执行前会调用，调用时接收到ApiRequestContext

/// <summary>
/// 定义ApiAction修饰特性的行为
/// </summary>
public interface IApiActionAttribute : IAttributeMultiplable
{
    /// <summary>
    /// 请求前
    /// </summary>
    /// <param name="context">上下文</param>
    /// <param name="next">下一个执行委托</param>
    /// <returns></returns>
    Task OnRequestAsync(ApiRequestContext context, Func<Task> next);
}

2 IApiParameterAttribute

表示参数执行前会调用，调用时接收到ApiParameterContext

/// <summary>
/// 定义Api参数修饰特性的行为
/// </summary>
public interface IApiParameterAttribute
{
    /// <summary>
    /// 请求前
    /// </summary>
    /// <param name="context">上下文</param>
    /// <param name="next">下一个执行委托</param>
    /// <returns></returns>
    Task OnRequestAsync(ApiParameterContext context, Func<Task> next);
}

3 IApiReturnAttribute

执行前和执行后都会收到，设置为上下文的Result或Exception，会短路执行

/// <summary>
/// 定义回复内容处理特性的行为
/// </summary>
public interface IApiReturnAttribute : IAttributeMultiplable, IAttributeEnable
{
    /// <summary>
    /// 请求前
    /// </summary>
    /// <param name="context">上下文</param>
    /// <param name="next">下一个执行委托</param>
    /// <returns></returns>
    Task OnRequestAsync(ApiRequestContext context, Func<Task> next);

    /// <summary>
    /// 响应后
    /// </summary>
    /// <param name="context">上下文</param>
    /// <param name="next">下一个执行委托</param>
    /// <returns></returns>
    Task OnResponseAsync(ApiResponseContext context, Func<Task> next);
}

5 IApiFilterAttribute

执行前和执行后都会收到，在IApiReturnAttribute之后执行

/// <summary>
/// 定义ApiAction过滤器修饰特性的行为
/// </summary>
public interface IApiFilterAttribute : IAttributeMultiplable, IAttributeEnable
{
/// <summary>
/// 请求前
/// </summary>
/// <param name="context">上下文</param>
/// <param name="next">下一个执行委托</param>
/// <returns></returns>
Task OnRequestAsync(ApiRequestContext context, Func<Task> next);

/// <summary>
/// 响应后
/// </summary>
/// <param name="context">上下文</param>
/// <param name="next">下一个执行委托</param>
/// <returns></returns>
Task OnResponseAsync(ApiResponseContext context, Func<Task> next);


}

结束语

代码可以写得很烂，但设计必须高大上，希望WebApiClientCore可以在声明式客户端领域继续引领其它开源库，同时让使用它的开发者为之赞叹。

如果你希望为望WebApiClientCore出力，可以Fork它然后pull request，和我一起完善单元测试，或编写多语言资源文件，或者加入一些更好的代码设计。