最近正好在频繁的调用第三方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
Over...
