BeetleX之HttpClusterApi应用详解

之前的文章已经介绍过如何使用HttpClusterApi进行去中心化的HTTP集群服务访问，这一章主要详细讲述如何使用HttpClusterApi，主要包括如何定义节点，创建服务接口和使用接口描述不同情况下的WebApi服务。最后通过HttpClusterApi简便地调用百度的一些云服务接口。

介绍

通过名称大概也能了解它的功能，通过它可以描述和调用不同的webapi服务应用；它提供了不同Url对应不同服务绑定和创建接口代理调用功能，从而让使用者通过接口的方式即可完成webapi的调用并不像传统WebHttpRequest或HttpClient那样编写大量繁琐的基础代码。

方法

组件提供了以下方法来添加服务地址

HttpClusterApi AddHost(string url, string host, int weight = 10)//设置url对应节点的host信息,默认权重是10,权重值可以根据自己实际情况来配置
HttpClusterApi AddHost(string url, params string[] host)//设置url对应节点的host信息,默认权重是10
HttpClusterApi SetNode(string url, IApiNode node)//设置url对应的节点信息

Url参数是一个正则表达式，用于匹配请求的url;当url值为*的时候该host是最低级匹配项,当没有任何匹配host的情况下才使用'*'对应的host.

INodeSourceHandler NodeSourceHandler { get; set; }

在之前的文章已经有所介绍,是用于自定义集群信息源,通过这个属性可以绑定集群信息来源,这样使用者就可以通过数据库,缓存或第方服务来加载集群负载信息.

 public T Create()

方法是创建一个接口代理,通过代理操作即可实现具体的HTTP请求,组件对接口的定义具有一定的限制性,虽然不用继承某些基础接口,但要通过一些组件提供的Attribute定义在方法或参数上.

 public ClusterStats Stats()

方法获取统计信息,可以得到每个url对应不同host的调用情况统计.

线程安全问题

HttpClusterApi是一个线程安全类,定义后可以在任意线程中同时使用;由于内部使用连接池的方式进行请求,所以并不用担心数据访问冲突的情况出现.Create返回的代理对象也是线程安全的,所以只需要创建一个接口实例接口即可随意调用.

接口定义

组件通过接口的方式来进行请求处理,所以并不需要编写任何基础的HTTP通讯代码,为了达到实际应用的需要,组件提供一些Attribute来代替基础代码的编写.下面介绍一些这些Attribute的作用.

请求描述

组件暂只支持GET,POST,PUT,DELETE这几种请求描述,这些属性只能标记在接口方法上,用于描述方法指向那种请求方式.Route属性用于描述请求的路径,默认是根路径并使用方法名称作为URL

   [AttributeUsage(AttributeTargets.Method)]
    public class GetAttribute : Attribute
    {
        public string Route { get; set; }
    }
    [AttributeUsage(AttributeTargets.Method)]
    public class PostAttribute : Attribute
    {
        public string Route { get; set; }
    }
    [AttributeUsage(AttributeTargets.Method)]
    public class DelAttribute : Attribute
    {
        public string Route { get; set; }
    }
    [AttributeUsage(AttributeTargets.Method)]
    public class PutAttribute : Attribute
    {
        public string Route { get; set; }
    }

数据转换器

数据转换器用于描述请求和响应数据流的处理方式,组件暂只提供两种转换器FormUrlFormater和JsonFormater,分别对应的Content-Type是:application/json和application/x-www-form-urlencoded.如果这两种都不能满足实际应用需要的情况下可以通过继承以下对象

    [AttributeUsage(AttributeTargets.Method | AttributeTargets.Interface | AttributeTargets.Class)]
    public abstract class FormaterAttribute : Attribute, IClientBodyFormater
    {
        public abstract string ContentType { get; }

        public abstract void Serialization(object data, PipeStream stream);

        public abstract object Deserialization(BeetleX.Buffers.PipeStream stream, Type type, int length);
    }

数据转换器可以标识在接口或方法上,如果方法有标识的情况下则方法标识的转换器优先使用.如果没有标记转换器组件默认使用FormUrlFormater

参数描述

在HTTP请求中主要有三种类型的参数,分别是Header,QueryString和Body;如果接口方法标记为POST或PUT的情况,方法参数默认是Body参数类型,会写入到HTTP的Body中.组件提供两个Attribute来描述参数应用到Header,和QueryString

CHeader

可以用于接口或方法上,并可以同时标记多个;当用在接口或方法的时候需要指定name和value.如果用在参数name和value都可以缺省,自动拿参数名和参数值.CHeader的内容会自动写入HTTP的header里.

CQuery

可以用于接口或方法上,并可以同时标记多个;当用在接口或方法的时候需要指定name和value.如果用在参数name和value都可以缺省,自动拿参数名和参数值.CQuery的内容会自动附加到URL上,并进行URL编码

SSL访问

组件并不需要针对SSL做特别的配置,会自动根据添加的host是不是https来确定,如果是https情况下组件会自动针对这host启用SSL配置.

百度车牌识别接口实现

考虑到实际应用的便利性,以下简单使用组件描述一下百度云下的车牌识别调用.

引用组件

接口功能定义

调用这个接口主要涉及到两个方法,先是获取access_token,然后再调用识别方法;针对这两个方法定义接口如下:

[BaiduApiFormater]
public interface IBaiduApi
{
     [Get(Route = "oauth/2.0/token")]
     [CQuery("client_id", "HiSRszPD******mqHfIz7VOrg")]
     [CQuery("client_secret", "y7MxdEIItD******YqtalU6b4iF")]
    Task GetToken(string grant_type = "client_credentials");
     [Post(Route = "rest/2.0/ocr/v1/license_plate")]
     Task Plate([CQuery]string access_token, string image, string multi_detect = "false");
}

由于百度的数据提交是application/x-www-form-urlencoded返回是josn;所以需要简单地实现一个对应的数据解释器

public class BaiduApiFormater : BeetleX.FastHttpApi.Clients.FormUrlFormater
    {
        public override object Deserialization(PipeStream stream, Type type, int length)
        {
            using (stream.LockFree())
            {
                if (type == null)
                {
                    using (System.IO.StreamReader streamReader = new System.IO.StreamReader(stream))
                    using (JsonTextReader reader = new JsonTextReader(streamReader))
                    {
                        JsonSerializer jsonSerializer = JsonSerializer.CreateDefault();
                        object token = jsonSerializer.Deserialize(reader);
                        return token;
                    }
                }
                else
                {
                    using (StreamReader streamReader = new StreamReader(stream))
                    {
                        JsonSerializer serializer = new JsonSerializer();
                        object result = serializer.Deserialize(streamReader, type);
                        return result;
                    }
                }
            }
        }
    }

相关工作准备好之后就可以使用接口进行功能调用了

BeetleX.FastHttpApi.Clients.HttpClusterApi httpClusterApi = new BeetleX.FastHttpApi.Clients.HttpClusterApi();
httpClusterApi.AddHost("*", "https://aip.baidubce.com");
IBaiduApi api = httpClusterApi.Create();
var token = await api.GetToken();
var result = await api.Plate(token.access_token, GetImageData());

这样一个百度车牌识别的接口调用就完成了,使用上是不是比传统的WebHttpRequest和httpclient要方便很多?