走进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
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，和我一起完善单元测试，或编写多语言资源文件，或者加入一些更好的代码设计。
