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

巴特西