一个简易的API调用框架

作者: 冰麟轻武 | 来源:发表于2017-05-09 01:15 被阅读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

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读

.NET

一个简易的API调用框架

一、定义接口

请求接口

执行器接口

二、基础类

会话类

基础执行器

Request抽象类

三、定义特性

四、定义异常

异常类

异常拓展类

五、Demo 一粒

首先定义一个翻译接口

继承ApSession实现一个会话类

添加配置文件

六、调用

七、Github

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读

.NET

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