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