一个简易的API调用框架

2017-05-09 本文已影响120人冰麟轻武

最近正好在频繁的调用第三方API，然鹅，部分第三方并不是很友好的没有给出SDK，所以为了调用方便设计了一个API调用框架

一、定义接口

请求接口

表示一个请求的所有参数，分为泛型和非泛型，方便在各种场合下使用
鉴于绝大部分正常人设计的API并不会要求在Cookie中设置参数，所以没有设置Cookie的属性
（ps：Cookie保持后面会涉及到，另外Cookie说白了也是Header，实在不行写个拓展方法直接操作Header得了）

    /// <summary>
    /// 表示一个Http请求
    /// </summary>
    /// <typeparam name="T"></typeparam>
    public interface IApRequest<out T>
    {
        /// <summary>
        /// 请求方法
        /// </summary>
        string Method { get; }
        /// <summary>
        /// 请求类型
        /// </summary>
        string ContentType { get; }
        /// <summary>
        /// 请求路径
        /// </summary>
        string Path { get; }
        /// <summary>
        /// 请求的Url参数
        /// </summary>
        IEnumerable<KeyValuePair<string, string>> Query { get; }
        /// <summary>
        /// 请求头参数
        /// </summary>
        IEnumerable<KeyValuePair<string, string>> Headers { get; }
        /// <summary>
        /// 请求正文
        /// </summary>
        byte[] Body { get; }
        /// <summary>
        /// 从响应中获取数据实体
        /// </summary>
        /// <param name="statusCode">响应码</param>
        /// <param name="content">响应正文</param>
        /// <param name="getHeader">用于获取请求头的委托</param>
        /// <returns></returns>
        T GetData(int statusCode, byte[] content, Func<string, string> getHeader);
    }

    /// <summary>
    /// 表示一个非泛型的Http请求
    /// </summary>
    public interface IApRequest : IApRequest<object>
    {

    }

执行器接口

表示一个执行请求的执行器
把BaseUrl和Path分开在实际操作中会带来很大便利，比如多套环境的切换

    /// <summary>
    /// 用于执行 <seealso cref="IApRequest{T}"/> 的执行器
    /// </summary>
    public interface IApWebInvoker
    {
        /// <summary>
        /// 使用异步方式发送请求并解析返回值
        /// </summary>
        /// <typeparam name="T">返回值类型</typeparam>
        /// <param name="baseUrl">基础Url</param>
        /// <param name="request">请求对象</param>
        /// <param name="cancellationToken">取消操作的取消标记</param>
        /// <returns></returns>
        Task<T> SendAsync<T>(Uri baseUrl, IApRequest<T> request, CancellationToken cancellationToken);

        /// <summary>
        /// 获取或设置请求超时前等待的毫秒数。
        /// </summary>
        TimeSpan Timeout { get; set; }
    }

二、基础类

会话类

表示一次会话
有很多接口都提供授权机制，有的通过access_token，有的通过session，无论如何，有一个会话实例会是一个很好的处理方式
会话中有一个ImportConfig方法，可以很方便的导入配置文件中的值到指定的属性中，它也提供了一些很基础的类型转换功能，当然它的确非常的基础，如果你愿意你可以将它完善
（ps：不过这需要一个ImportConfigAttribute的支持，在下面会提到他）

    /// <summary>
    /// 表示一个会话
    /// </summary>
    public class ApSession
    {
        /// <summary>
        /// 请求执行器
        /// </summary>
        public IApWebInvoker Invoker { get; }

        /// <summary>
        /// 表示一个会话, 默认使用 <seealso cref="ApWebInvoker"/> 执行器
        /// </summary>
        public ApSession() => Invoker = new ApWebInvoker();

        /// <summary>
        /// 表示一个会话, 并指定一个执行器
        /// </summary>
        /// <param name="invoker"></param>
        public ApSession(IApWebInvoker invoker) => Invoker = invoker ?? new ApWebInvoker();

        /// <summary>
        /// 导入配置
        /// </summary>
        /// <param name="getConfig">用于获取配置值的委托</param>
        public void ImportConfig(Func<string, string> getConfig)
        {
            var props = from p in GetType().GetRuntimeProperties()
                        where p.CanWrite && !p.SetMethod.IsStatic
                        let a = p.GetCustomAttribute<ImportConfigAttribute>()
                        where a != null
                        select new KeyValuePair<string, PropertyInfo>(a.Name ?? p.Name, p);
            foreach (var p in props)
            {
                var value = (object)getConfig(p.Key);
                if (value != null)
                {
                    if (p.Value.PropertyType != typeof(Uri))
                    {
                        value = new Uri((string)value);
                    }
                    else if (p.Value.PropertyType != typeof(string))
                    {
                        value = Convert.ChangeType(value, p.Value.PropertyType);
                    }
                    p.Value.SetValue(this, value);
                }
            }
        }

        protected Task<T> Invoke<T>(string baseUrl, IApRequest<T> request, CancellationToken cancellationToken)
        {
            try
            {
                return Invoker.SendAsync(new Uri(baseUrl), request, cancellationToken);
            }
            catch (Exception e)
            {
                Debug.WriteLine(e);
                throw e.RequestException(1);
            }
        }
    }

基础执行器

这是一个基于System.Net.Http.HttpClient实现的IApWebInvoker

    /// <summary>
    /// 使用 <seealso cref="HttpClient"/> 执行 <seealso cref="IApRequest{T}"/> 的执行器
    /// </summary>
    public class ApWebInvoker : IApWebInvoker
    {
        /// <summary>
        /// 用于执行请求的 <seealso cref="HttpClient"/>
        /// </summary>
        private static readonly HttpClient _client = new HttpClient();

        /// <summary>
        /// 获取或设置请求超时前等待的毫秒数。
        /// </summary>
        public TimeSpan Timeout
        {
            get => _client.Timeout;
            set => _client.Timeout = value;
        }

        /// <summary>
        /// 将字符串转为 <seealso cref="HttpMethod"/>
        /// </summary>
        /// <param name="method">待转换的字符串</param>
        /// <returns></returns>
        private static HttpMethod ToHttpMethod(string method)
        {
            switch (method?.ToUpperInvariant())
            {
                case "GET":
                case null:
                    return HttpMethod.Get;
                case "DELETE":
                    return HttpMethod.Delete;
                case "HEAD":
                    return HttpMethod.Head;
                case "OPTIONS":
                    return HttpMethod.Options;
                case "POST":
                    return HttpMethod.Post;
                case "PUT":
                    return HttpMethod.Put;
                case "TRACE":
                    return HttpMethod.Trace;
                default:
                    return new HttpMethod(method);
            }
        }

        /// <summary>
        /// 使用异步方式发送请求并解析返回值
        /// </summary>
        /// <typeparam name="T">返回值类型</typeparam>
        /// <param name="baseUrl">基础路径</param>
        /// <param name="request">请求对象</param>
        public Task<T> SendAsync<T>(string baseUrl, IApRequest<T> request)
            => SendAsync(new Uri(baseUrl), request, CancellationToken.None);

        /// <summary>
        /// 使用异步方式发送请求并解析返回值
        /// </summary>
        /// <typeparam name="T">返回值类型</typeparam>
        /// <param name="baseUrl">基础路径</param>
        /// <param name="request">请求对象</param>
        /// <param name="cancellationToken">取消操作的取消标记</param>
        public Task<T> SendAsync<T>(string baseUrl, IApRequest<T> request, CancellationToken cancellationToken)
            => SendAsync(new Uri(baseUrl), request, cancellationToken);

        /// <summary>
        /// 使用异步方式发送请求并解析返回值
        /// </summary>
        /// <typeparam name="T">返回值类型</typeparam>
        /// <param name="baseUrl">基础路径</param>
        /// <param name="request">请求对象</param>
        public Task<T> SendAsync<T>(Uri baseUrl, IApRequest<T> request)
            => SendAsync(baseUrl, request, CancellationToken.None);

        /// <summary>
        /// 使用异步方式发送请求并解析返回值
        /// </summary>
        /// <typeparam name="T">返回值类型</typeparam>
        /// <param name="baseUrl">基础路径</param>
        /// <param name="request">请求对象</param>
        /// <param name="cancellationToken">取消操作的取消标记</param>
        /// <returns></returns>
        public async Task<T> SendAsync<T>(Uri baseUrl, IApRequest<T> request, CancellationToken cancellationToken)
        {
            if (request == null) throw new ArgumentNullException(nameof(request));
            var url = new UriBuilder(new Uri(baseUrl, request.Path));
            var encode = new FormUrlEncodedContent(request.Query);
            var query = await encode.ReadAsStringAsync();
            if (url.Query.Length > 1)
            {
                url.Query += "&" + query;
            }
            else
            {
                url.Query = query;
            }

            var method = ToHttpMethod(request.Method);
            var message = new HttpRequestMessage(method, url.Uri);
            if (request.Headers != null)
            {
                foreach (var header in request.Headers)
                {
                    message.Headers.TryAddWithoutValidation(header.Key, header.Value);
                }
            }

            var body = request.Body;
            if (body != null)
            {
                var contentType = request.ContentType;
                message.Content = new ByteArrayContent(request.Body);
                message.Content.Headers.ContentType = contentType == null ? null : MediaTypeHeaderValue.Parse(contentType);
            }

            var response = await _client.SendAsync(message, cancellationToken);
            var statusCode = (int)response.StatusCode;
            var content = await response.Content.ReadAsByteArrayAsync();

            return request.GetData(statusCode, content, name => response.Headers.TryGetValues(name, out var values) ? string.Join(", ", values) : null);
        }
    }

Request抽象类

定义一个抽象类将在实际使用中更方便，它可以设定很多默认值和默认实现，这将大大的减少实现类的代码

    /// <summary>
    /// Http请求的抽象基类
    /// </summary>
    /// <typeparam name="T"></typeparam>
    public abstract class ApRequest<T> : IApRequest<T>
    {
        /// <summary>
        /// 请求方法, 默认: GET
        /// </summary>
        public virtual string Method { get; } = "GET";

        /// <summary>
        /// 请求路径
        /// </summary>
        public abstract string Path { get; }

        /// <summary>
        /// 请求类型, 默认: null
        /// </summary>
        public virtual string ContentType
            => EnumerableBodyProperties().FirstOrDefault().Value?.ContentType;

        /// <summary>
        /// 请求的Url参数, 默认获取被标记为 <seealso cref="QueryValueAttribute"/> 的属性值
        /// </summary>
        public virtual IEnumerable<KeyValuePair<string, string>> Query
            => from x in GetType().GetRuntimeProperties()
               let a = x.GetCustomAttribute<QueryValueAttribute>()
               where a != null
               select new KeyValuePair<string, string>(a.Name ?? x.Name, x.GetValue(this)?.ToString());

        /// <summary>
        /// 请求头参数, 默认获取被标记为 <seealso cref="HeaderValueAttribute"/> 的属性值
        /// </summary>
        public virtual IEnumerable<KeyValuePair<string, string>> Headers
            => from x in GetType().GetRuntimeProperties()
               let a = x.GetCustomAttribute<HeaderValueAttribute>()
               where a != null
               select new KeyValuePair<string, string>(a.Name ?? x.Name, x.GetValue(this)?.ToString());

        /// <summary>
        /// 枚举被标记为 <seealso cref="BodyValueAttribute"/> 的属性
        /// </summary>
        /// <returns></returns>
        private IEnumerable<KeyValuePair<PropertyInfo, BodyValueAttribute>> EnumerableBodyProperties()
            => from property in GetType().GetRuntimeProperties()
               let body = property.GetCustomAttribute<BodyValueAttribute>()
               where body != null
               select new KeyValuePair<PropertyInfo, BodyValueAttribute>(property, body);

        /// <summary>
        /// 请求正文, 根据实际情况计算Body的值
        /// </summary>
        public virtual byte[] Body
        {
            get
            {
                if (ContentType == null)
                {
                    return null;
                }
                if (ContentType.Contains("x-www-form-urlencoded"))
                {
                    var nv = from x in GetType().GetRuntimeProperties()
                             let a = x.GetCustomAttribute<BodyValueAttribute>()
                             where a != null
                             select new KeyValuePair<string, string>(a.Name ?? x.Name, x.GetValue(this)?.ToString());
                    return new FormUrlEncodedContent(nv).ReadAsByteArrayAsync().ConfigureAwait(false).GetAwaiter().GetResult();
                }
                throw new NotImplementedException();
            }
        }

        /// <summary>
        /// 从响应中获取数据实体
        /// </summary>
        /// <param name="statusCode">响应码</param>
        /// <param name="content">响应正文</param>
        /// <param name="getHeader">用于获取请求头的委托</param>
        /// <returns></returns>
        public abstract T GetData(int statusCode, byte[] content, Func<string, string> getHeader);
    }

三、定义特性

除了ImportConfigAttribute服务于ApSession类
其他特性服务于ApRequest

    /// <summary>
    /// 特性基类
    /// </summary>
    [AttributeUsage(AttributeTargets.Property)]
    public abstract class AttributeBase : Attribute
    {
        /// <summary>
        /// 参数或配置名称
        /// </summary>
        public string Name { get; set; }
    }

    /// <summary>
    /// 表示请求Url参数
    /// </summary>
    [AttributeUsage(AttributeTargets.Property)]
    public sealed class QueryValueAttribute : AttributeBase { }
    /// <summary>
    /// 表示请求头参数
    /// </summary>
    [AttributeUsage(AttributeTargets.Property)]
    public sealed class HeaderValueAttribute : AttributeBase { }
    /// <summary>
    /// 表示属性关联指定配置
    /// </summary>
    [AttributeUsage(AttributeTargets.Property)]
    public sealed class ImportConfigAttribute : AttributeBase { }
    /// <summary>
    /// 表示请求正文参数
    /// </summary>
    [AttributeUsage(AttributeTargets.Property)]
    public sealed class BodyValueAttribute : AttributeBase
    {
        /// <summary>
        /// 请求正文类型
        /// </summary>
        public string ContentType { get; }
        /// <summary>
        /// 表示请求正文参数
        /// </summary>
        public BodyValueAttribute() { }
        /// <summary>
        /// 表示请求正文参数
        /// </summary>
        /// <param name="type">简化请求类型</param>
        public BodyValueAttribute(string type = "form")
            => ContentType = ToContentType(type ?? throw new ArgumentNullException(nameof(type)));
        /// <summary>
        /// 将简化的字符串转为标准 ContentType
        /// </summary>
        /// <param name="type">简化请求类型</param>
        /// <returns></returns>
        public static string ToContentType(string type)
        {
            switch (type?.ToLowerInvariant())
            {
                case "form":
                case "urlencode":
                    return "application/x-www-form-urlencoded";
                case "xml":
                    return "text/xml;charset=utf-8";
                case "json":
                    return "application/json;charset=utf-8";
                case "string":
                case "text":
                    return "text/plain;charset=utf-8";
                case "protobuf":
                    return "application/x-protobuf;charset=utf-8";
                default:
                    return type ?? "";
            }
        }
    }

四、定义异常

异常类

为了区分异常，一般各个组件都会定义属于自己的异常类
鉴于api一般会有错误码的设定，所以异常类增加一个属性ErrCode，大部分异常码均为string或int，由于系统的Exception自带一个HResult属性是int类型的，所以将自定义的ErrCode属性定义为string类型
（ps：部分比较BT的API也有可能会返回float的错误码，可以用string兼容）

    /// <summary>
    /// 请求异常
    /// </summary>
    public class ApRequestException : Exception
    {
        /// <summary>
        /// 异常码
        /// </summary>
        public string ErrCode { get; }

        /// <summary>
        /// 请求异常
        /// </summary>
        /// <param name="errcode">异常码</param>
        /// <param name="message">异常消息</param>
        public ApRequestException(int errcode, string message)
            : base(message)
        {
            HResult = errcode;
            ErrCode = errcode.ToString();
        }

        /// <summary>
        /// 请求异常
        /// </summary>
        /// <param name="errcode">异常码</param>
        /// <param name="message">异常消息</param>
        /// <param name="inner">内部异常</param>
        public ApRequestException(int errcode, string message, Exception inner)
            : base(message, inner)
        {
            HResult = errcode;
            ErrCode = errcode.ToString();
        }

        /// <summary>
        /// 请求异常
        /// </summary>
        /// <param name="errcode">异常码</param>
        /// <param name="message">异常消息</param>
        public ApRequestException(string errcode, string message)
            : base(message)
        {
            ErrCode = errcode;
        }

        /// <summary>
        /// 请求异常
        /// </summary>
        /// <param name="errcode">异常码</param>
        /// <param name="message">异常消息</param>
        /// <param name="inner">内部异常</param>
        public ApRequestException(string errcode, string message, Exception inner)
            : base(message, inner)
        {
            ErrCode = errcode;
        }
    }

异常拓展类

用于将任何异常转为ApRequestException

    /// <summary>
    /// 拓展方法
    /// </summary>
    public static class ApExtensions
    {
        /// <summary>
        /// 将异常转为 <seealso cref="ApRequestException"/>
        /// </summary>
        /// <param name="exception">转换前的异常</param>
        /// <param name="errorCode">错误码</param>
        /// <returns></returns>
        public static ApRequestException RequestException(this Exception exception, int errorCode)
            => new ApRequestException(errorCode, exception?.Message ?? "未知异常", exception);

        /// <summary>
        /// 将异常转为 <seealso cref="ApRequestException"/>
        /// </summary>
        /// <param name="exception">转换前的异常</param>
        /// <param name="errorCode">错误码</param>
        public static ApRequestException RequestException(this Exception exception, string errorCode)
            => new ApRequestException(errorCode, exception?.Message ?? "未知异常", exception);
    }

五、Demo 一粒

比如之前的一个Bing的翻译接口（现在已经不能用了）
他的接口地址是
https://api.datamarket.azure.com/Bing/MicrosoftTranslator/v1/Translate
授权方式采用Authorization Basic
参数2个分别为Text（表示要翻译的文本）和To（表示翻译后的语言代码），比较特殊的是这2个参数需要使用一对单引号包起来
且返回的是一个xml

所以可以这样

首先定义一个翻译接口

   class TranslateV1 : ApRequest<string>
    {
        [Header]
        public string Authorization { get; set; }
        [Query]
        public string Text { get; }
        [Query]
        public string To { get; }

        public TranslateV1(string text, string to = "zh-CHS")
        {
            Text = $"'{text}'";
            To = $"'{to}'";
        }

        public override string Path => "/Bing/MicrosoftTranslator/v1/Translate";

        public override string GetData(int statusCode, byte[] content, Func<string, string> getHeader)
        {
            if (statusCode != 200)
            {
                return "翻译失败";
            }
            const string START = "<d:String m:type=\"Edm.String\">";
            const string END = "</d:String>";
            var str = Encoding.UTF8.GetString(content);
            var start = str.IndexOf(START, StringComparison.Ordinal);
            if (start < 0)
            {
                return "翻译失败";
            }
            start += START.Length;
            var end = str.IndexOf(END, start, StringComparison.Ordinal);
            return str.Substring(start, end - start);
        }
    }

继承ApSession实现一个会话类

如果需要保持cookie或accesstoken`，可以在会话类中保存一个属性

    class Bing : ApSession
    {
        public Bing()
            : base(new ApWebInvoker())
        {
            ImportConfig(x => ConfigurationManager.AppSettings[x]);
            Invoker.BaseUrl = new Uri(Url);
        }

        [ImportConfig("Bing.Url")]
        public Uri Url { get; set; }

        [ImportConfig("Bing.Authorization")]
        public string Authorization { get; set; }


        public Task<string> TranslateToCN(string text)
        {
            return SendAsync(Url, new TranslateV1(text)
            {
                Authorization = Authorization
            });
        }
    }

添加配置文件

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="Bing.Url" value="https://api.datamarket.azure.com"/>
    <add key="Bing.Authorization" value="Basic NjBhYzBhNmQtMzkwMi00YT*****"/>
  </appSettings>
</configuration>

六、调用

    public class Program
    {
        static void Main(string[] args)
        {
            Translate();
        }

        static readonly Bing _session = new Bing();
        private static async void Translate()
        {
            var text = await _session.TranslateToCN("hello");
            Console.WriteLine(text);
        }
    }

七、Github

https://github.com/blqw/blqw.Apilay

Over...

一个简易的API调用框架

一、定义接口

请求接口

执行器接口

二、基础类

会话类

基础执行器

Request抽象类

三、定义特性

四、定义异常

异常类

异常拓展类

五、Demo 一粒

首先定义一个翻译接口

继承`ApSession`实现一个会话类

添加配置文件

六、调用

七、Github

猜你喜欢

热点阅读

一个简易的API调用框架

一、定义接口

请求接口

执行器接口

二、基础类

会话类

基础执行器

Request抽象类

三、定义特性

四、定义异常

异常类

异常拓展类

五、Demo 一粒

首先定义一个翻译接口

继承ApSession实现一个会话类

添加配置文件

六、调用

七、Github

猜你喜欢

热点阅读

继承`ApSession`实现一个会话类