XMNetworking 网络库的设计与使用
2019独角兽企业重金招聘Python工程师标准>>>
XMNetwoking 是我们团队开源的一个网络库,详见:GitHub
XMNetworking 是一个轻量的、简单易用但功能强大的网络库,基于 AFNetworking 3.0 封装。
其中,XM
前缀是我们团队 Xcode-Men 的缩写。英文文档
简介
XMNetworking.png
如上图所示,XMNetworking 采用中心化的设计思想,由 XMCenter
统一发起并管理所有的 XMRequest
请求,并可通过 XMCenter
给所有请求配置回调线程、公共 Server URL、Header、Parameter 等信息,同时也可以 Block 注入的方式实现自定义的响应结果处理逻辑,如数据模型转换、业务错误码判断、网络缓存等。另外增加了 XMEgine
这一层是为了隔离底层第三方库依赖,便于以后切换其他底层网络库或自己实现底层逻辑。
特性
- 简单易用,发送请求只需调用一个方法,通过 Block 配置信息,代码紧凑;
- 功能强大,适用于几乎所有的网络请求使用场景(普通请求、上传、下载);
- 专为 RESTful Server API 设计,并提供多种不同的请求和响应的序列化类型;
- 支持批量请求、链式请求等复杂业务逻辑的网络需求;
- 可随时取消未完成的网络请求,支持自动重试失败的请求;
- 全局配置所有请求的公共信息,自定义回调线程以及响应处理逻辑;
- 支持检查网络连接类型,并集成 AFNetworking 强大的安全策略模块。
系统要求
- iOS 7.0 以上系统
- Xcode 7.3 或更高版本
安装说明
CocoaPods
在你工程的 Podfile
文件中添加如下一行,并执行 pod install
或 pod update
。
pod 'XMNetworking'
注意: XMNetworking
已经包含了 AFNetworking
3.1.0 的源代码,所以你工程里的 Podfile
文件不能再添加 pod AFNetworking
去导入 AFNetworking
,否则会有冲突!
Carthage (只支持 iOS 8+)
与 CocoaPods 不同的是,Carthage 是一个去中心化的第三方依赖库管理工具,它自动帮你编译所依赖的第三方库并以 framework 形式提供给你。
你可以通过 Homebrew 执行以下命令来安装 Carthage:
$ brew update
$ brew install carthage
成功安装完 Carthage 后,在你工程的 Cartfile
文件中添加如下一行:
github "kangzubin/XMNetworking"
然后执行 carthage update --platform ios
命令生成 framework 包,并把生成的 XMNetworking.framework
拖拽到你的工程中。
注意: XMNetworking
已经包含了 AFNetworking
3.1.0 的源代码,所以你无需通过 Carthage 生成 AFNetworking.framework
导到你工程中,否则会有冲突!
手动安装
下载 XMNetworking
子文件夹的所有内容,并把其中的源文件添加(拖放)到你的工程中。
使用教程
头文件的导入
- 如果是通过 CocoaPods 或 Carthage 安装,则:
#import <XMNetworking/XMNetworking.h>
- 如果是手动下载源码安装,则:
#import "XMNetworking.h"
全局网络配置
[XMCenter setupConfig:^(XMConfig *config) {config.generalServer = @"general server address";config.generalHeaders = @{@"general-header": @"general header value"};config.generalParameters = @{@"general-parameter": @"general parameter value"};config.generalUserInfo = nil;config.callbackQueue = dispatch_get_main_queue();
#ifdef DEBUGconfig.consoleLog = YES;
#endif
}];
你可以调用 XMCenter
的 +setupConfig:
类方法,通过修改传入的 XMConfig
对象来配置全局网络请求的公共信息,包括如下:
- generalServer: 公共服务端地址,如果一个 XMRequest 请求对象的
server
属性为nil
,且其useGeneralServer
为YES
(默认),那么该请求的服务端地址server
将会取 XMCenter 中generalServer
的值。 - generalParameters: 公共请求参数,如果一个 XMRequest 请求对象的
useGeneralParameters
属性为YES
(默认),并且 XMCenter 的公共参数generalParameters
不为空,那么这些公共参数会自动加到该请求的parameters
中。 - generalHeaders: 公共请求头,如果一个 XMRequest 请求对象的
useGeneralHeaders
属性为YES
(默认),并且 XMCenter 的公共请求头generalHeaders
不为空,那么这些公共请求头会自动加到该请求的headers
中。 - generalUserInfo: 公共用户信息,默认为
nil
,如果一个 XMRequest 请求对象的userInfo
属性为nil
(默认)而该字段不为nil
,那么该字段会自动赋值给XMRequest
对象的userInfo
。而userInfo
属性可用于区分具有相同上下文信息的不同请求。 - callbackQueue: 请求的回调 Block 执行的 dispatch 队列(线程),如果为
NULL
(默认),那么会在一个私有的并发队列(子线程)中执行回调 Block。 - consoleLog: 一个
BOOL
值,用于表示是否在控制台输出请求和响应的信息,默认为NO
。
另外,你可以通过调用 XMCenter
的以下两个类方法来随时修改全局公共的 header 和 parameter:
+ (void)setGeneralHeaderValue:(nullable NSString *)value forField:(NSString *)field;
+ (void)setGeneralParameterValue:(nullable NSString *)value forKey:(NSString *)key;
普通请求
GET
[XMCenter sendRequest:^(XMRequest *request) {request.url = @"http://example.com/v1/foo/bar";//request.server = @"http://example.com/v1/";//request.api = @"foo/bar";request.parameters = @{@"param1": @"value1", @"param2": @"value2"};request.headers = @{@"User-Agent": @"Custom User Agent"};request.httpMethod = kXMHTTPMethodGET;
} onSuccess:^(id responseObject) {NSLog(@"onSuccess: %@", responseObject);
} onFailure:^(NSError *error) {NSLog(@"onFailure: %@", error);
} onFinished:^(id responseObject, NSError *error) {NSLog(@"onFinished");
}];
注意1:可以通过以下两种方法设置一个请求对象的 URL 地址,但当 server
、api
和 url
三个属性被同时赋值时,url
的优先级比较高,而此时 server
、api
的值会被忽略。
request.url = @"http://example.com/v1/foo/bar";
// 如果 request.server 为 `nil`,且 request.useGeneralServer 为 `YES`,那么此时 request.server 会取 XMCenter.generalServer 的值。
request.server = @"http://example.com/v1/";
request.api = @"foo/bar";
注意2:一个请求对象的回调 Block (success/failure/finished/progress) 是非必需的(默认为 nil
),XMCenter 提供了多个设置不同回调 Block 参数的方法用于发送请求。另外,需要注意的是,success/faillure/finished 等回调 Block 会在 XMCenter 设置的 callbackQueue
队列中被执行,但 progress 回调 Block 将在 NSURLSession 自己的队列中执行,而不是 callbackQueue
。
POST
[XMCenter sendRequest:^(XMRequest *request) {//request.server = @"http://example.com/v1/"; // 可选,如果为空则读取 XMCenter.generalServerrequest.api = @"foo/bar";request.parameters = @{@"param1": @"value1", @"param2": @"value2"};request.httpMethod = kXMHTTPMethodPOST; // 可选,默认为 `POST`request.requestType = kXMRequestNormal; // 可选,默认为 `Normal`
} onSuccess:^(id responseObject) {NSLog(@"onSuccess: %@", responseObject);
} onFailure:^(NSError *error) {NSLog(@"onFailure: %@", error);
}];
其他 HTTP 方法
XMRequest 同样支持其他 HTTP 方法,比如:HEAD
, DELETE
, PUT
, PATCH
等,使用方式与上述类似,不再赘述。
详见 XMConst
、XMRequest
和 XMCenter
等几个文件中的代码和注释。
上传请求
// `NSData` form data.
UIImage *image = [UIImage imageNamed:@"testImage"];
NSData *fileData1 = UIImageJPEGRepresentation(image, 1.0);
// `NSURL` form data.
NSString *path = [NSHomeDirectory() stringByAppendingString:@"/Documents/testImage.png"];
NSURL *fileURL2 = [NSURL fileURLWithPath:path isDirectory:NO];[XMCenter sendRequest:^(XMRequest *request) {request.server = @"http://example.com/v1/";request.api = @"foo/bar";request.requestType = kXMRequestUpload;[request addFormDataWithName:@"image[]" fileName:@"temp.jpg" mimeType:@"image/jpeg" fileData:fileData1];[request addFormDataWithName:@"image[]" fileURL:fileURL2];// see `XMUploadFormData` for more details.
} onProgress:^(NSProgress *progress) {// the progress block is running on the session queue.if (progress) {NSLog(@"onProgress: %f", progress.fractionCompleted);}
} onSuccess:^(id responseObject) {NSLog(@"onSuccess: %@", responseObject);
} onFailure:^(NSError *error) {NSLog(@"onFailure: %@", error);
} onFinished:^(id responseObject, NSError *error) {NSLog(@"onFinished");
}];
下载请求
[XMCenter sendRequest:^(XMRequest *request) {request.url = @"http://example.com/v1/testDownFile.zip";request.downloadSavePath = [NSHomeDirectory() stringByAppendingString:@"/Documents/"];request.requestType = kXMRequestDownload;
} onProgress:^(NSProgress *progress) {// the progress block is running on the session queue.if (progress) {NSLog(@"onProgress: %f", progress.fractionCompleted);}
} onSuccess:^(id responseObject) {NSLog(@"onSuccess: %@", responseObject);
} onFailure:^(NSError *error) {NSLog(@"onFailure: %@", error);
}];
序列化
XMRequest
中有两个属性 requestSerializerType
和 responseSerializerType
分别用于设置请求参数和响应结果的序列化类型。
其中,XMRequestSerializerType
和 XMResponseSerializerType
枚举的定义如下:
typedef NS_ENUM(NSInteger, XMRequestSerializerType) {kXMRequestSerializerRAW = 0, // defaultkXMRequestSerializerJSON = 1,kXMRequestSerializerPlist = 2,
};
typedef NS_ENUM(NSInteger, XMResponseSerializerType) {kXMResponseSerializerRAW = 0,kXMResponseSerializerJSON = 1, // defaultkXMResponseSerializerPlist = 2,kXMResponseSerializerXML = 3,
};
详见 AFURLRequestSerialization.h
和 AFURLResponseSerialization.h
获取更多细节。
自定义响应结果的处理逻辑
通常地,一个请求成功结束时,会执行 success block,当有错误发生时,执行 failure block。然而,开发中更常见的情况是,即使是一个请求成功结束,我们也需要进一步处理,比如验证响应结果数据、判断与服务端商量好的业务错误码类型等,再决定执行 success block 还是 failure block。
现在,你可以调用 [XMCenter setResponseProcessBlock:...]
方法以 Block 注入的方式设置自定义的处理逻辑,当请求成功结束时,这个 Block 会在 success block 被执行前调用,如果传入 *error
参数被赋值,则接下来会执行 failure block。
[XMCenter setResponseProcessBlock:^(XMRequest *request, id responseObject, NSError *__autoreleasing *error) {// 自定义响应结果处理逻辑,如果 `*error` 被赋值,则接下来会执行 failure block。
}];
批量请求
XMNetworking 支持同时发一组批量请求,这组请求在业务逻辑上相关,但请求本身是互相独立的,success block 会在所有请求都成功结束时才执行,而一旦有一个请求失败,则会执行 failure block。注:回调 Block 中的 responseObjects
和 errors
中元素的顺序与每个 XMRequest 对象在 batchRequest.requestArray
中的顺序一致。
[XMCenter sendBatchRequest:^(XMBatchRequest *batchRequest) {XMRequest *request1 = [XMRequest request];request1.url = @"server url 1";// set other properties for request1XMRequest *request2 = [XMRequest request];request2.url = @"server url 2";// set other properties for request2[batchRequest.requestArray addObject:request1];[batchRequest.requestArray addObject:request2];
} onSuccess:^(NSArray<id> *responseObjects) {NSLog(@"onSuccess: %@", responseObjects);
} onFailure:^(NSArray<id> *errors) {NSLog(@"onFailure: %@", errors);
} onFinished:^(NSArray<id> *responseObjects, NSArray<id> *errors) {NSLog(@"onFinished");
}];
[XMCenter sendBatchRequest:...]
方法会返回刚发起的新的 XMBatchRequest
对象,你可以保存这个对象,并在必要的时候调用它的 -cancelWithBlock:
方法取消这组批量请求。
链式请求
XMNetworking 同样支持发一组链式请求,这组请求之间互相依赖,下一请求是否发送以及请求的参数取决于上一个请求的结果,success block 会在所有的链式请求都成功结束时才执行,而中间一旦有一个请求失败,则会执行 failure block。注:回调 Block 中的 responseObjects
和 errors
中元素的顺序与每个链式请求 XMRequest
对象的先后顺序一致。
[XMCenter sendChainRequest:^(XMChainRequest *chainRequest) {[[[[chainRequest onFirst:^(XMRequest *request) {request.url = @"server url 1";// set other properties for request}] onNext:^(XMRequest *request, id responseObject, BOOL *sendNext) {NSDictionary *params = responseObject;if (params.count > 0) {request.url = @"server url 2";request.parameters = params;} else {*sendNext = NO;}}] onNext:^(XMRequest *request, id responseObject, BOOL *sendNext) {request.url = @"server url 3";request.parameters = @{@"param1": @"value1", @"param2": @"value2"};}] onNext: ...];
} onSuccess:^(NSArray<id> *responseObjects) {NSLog(@"onSuccess: %@", responseObjects);
} onFailure:^(NSArray<id> *errors) {NSLog(@"onFailure: %@", errors);
} onFinished:^(NSArray<id> *responseObjects, NSArray<id> *errors) {NSLog(@"onFinished");
}];
[XMCenter sendChainRequest:...]
方法会返回刚发起的新的 XMChainRequest
对象,你可以保存这个对象,并在必要的时候调用它的 -cancelWithBlock:
方法取消这组链式请求。
取消一个网络请求
当调用 [XMCenter sendRequest:...]
方法发送一个网络请求时,该方法会返回一个用于唯一标识该请求对象的 identifier
(如果请求发送失败,该值为 0
)。在必要的时候,你可以通过这个 identifier
来取消当前网络请求(如果一个请求已经结束,这时再用 identifier
来取消该请求时,会直接忽略)。
// send a request
NSUInteger identifier = [XMCenter sendRequest:^(XMRequest *request) {request.server = @"https://kangzubin.cn/";request.api = @"test/index.php";request.httpMethod = kXMHTTPMethodGET;request.timeoutInterval = 10;request.retryCount = 1;
} onFailure:^(NSError *error) {NSLog(@"onFailure: %@", error);
}];// your business code
sleep(2);// cancel the running request by identifier with cancel block
[XMCenter cancelRequest:identifier onCancel:^(XMRequest *request) {NSLog(@"onCancel");
}];
注意:调用 XMCenter cancelRequest:onCancel:
方法取消一个网络请求时,被取消的请求对象(如果存在)会以参数的形式传给 cancel block,另外 cancel block 是在当前调用 cancelRequest:
方法的线程中执行,并不是 XMCenter 的 callbackQueue
。
网络可连接性检查
我们提供了两种方法用于获取网络的可连接性,分别如下:
[XMCenter isNetworkReachable];
// 该方法会返回一个 Bool 值用于表示当前网络是否可连接。
[[XMEngine sharedEngine] networkReachability];
// 该方法会返回一个当前网络的状态值,-1 表示 `Unknown`,0 表示 `NotReachable,1 表示 `WWAN`,2 表示 `WiFi`
详见 AFNetworkReachabilityManager
获取更多细节.
HTTPS 请求的本地证书校验(SSL Pinning)
在你的应用程序包里添加 (pinned) 相应的 SSL 证书做校验有助于防止中间人攻击和其他安全漏洞。非常方便的是,AFNetworking 的 AFSecurityPolicy
安全模块可以通过校验本地保存的证书或公钥帮助我们评估服务器是否可信任以及建立安全连接。
我们在 XMEngine
中暴露了一个 AFHTTPSessionManager
对象叫 sessionManager
,你可以通过修改该对象的 securityPolicy
类型,以开启 SSL Pinning 功能,并把你们服务器对应的 .cer
证书或者公钥放到你的工程中。
[XMEngine sharedEngine].sessionManager.securityPolicy = [AFSecurityPolicy policyWithPinningMode:AFSSLPinningModeCertificate];
详见 AFSecurityPolicy
获取更多细节.
文档
详见 XMNetworking Documents Link.
结构
XMNetworking 的代码结构非常简洁和紧凑,只包含了 4 个核心文件:XMConst.h
用于定义全局常量枚举和 Block,XMRequest
,XMCenter
和 XMEngine
则是核心类的声明和实现,具体的代码结构如下图所示:
Architecture.png
待完善
- 支持断点下载
- 支持网络层缓存
- 兼容测试支持 tvOS/watchOS/OS X
- 更加强大的自定义模型转换
- 实现一套可扩展的插件机制,便于 XMNetworking 增加新功能
作者
- Zubin Kang
贡献者
- southpeak
- Xcode-Men Team
许可证
XMNetworking 使用 MIT 许可证,详情见 LICENSE 文件。
文/XcodeMen(简书作者)
原文链接:http://www.jianshu.com/p/a5c5e9aa5913
转载于:https://my.oschina.net/u/2345393/blog/810373
XMNetworking 网络库的设计与使用相关推荐
- 技术实践 | 聊聊网易云信的信令网络库实践
导读:信令作为实时音视频技术架构中的重要一环,是对建立实时音视频通信起到关键桥梁性的作用. 文|丁永锋 网易云信资深客户端开发工程师 本文将从信令的概念着手,分享在网易云信新一代音视频技术架构下,信令 ...
- moudo网络库剖析
muduo简介 muduo是陈硕大神在Linux平台下基于C/C++开发的高性能网络库,在此基础上可以很方便的扩展,进行二次开发编写如http服务器.muduo网络库的核心框架,one thread ...
- C++练手项目(基于muduo网络库+mysql+jsoncpp的简易HTTPWebServer用于网页显示数据库后台数据
基于muduo网络库+mysql+jsoncpp的简易HTTPWebServer 项目介绍 背景介绍 主要模块介绍 1.基于muduo网络库的WebServer: 2.HTTP协议栈 3.JsonSe ...
- libuv 网络库设计概览译
设计概览 libuv 是一种支持跨平台的网络库,最初是为了NodeJS作为某个模块实现的,主要基于事件驱动的I/O 模型设计的. 这个库不仅仅对不同的I/O polling 机制提供简单的抽象. ha ...
- muduo网络库设计与实现(二)
muduo网络库设计与实现(一) 文章目录 muduo网络库设计与实现(一) base InetAddress Socket 单线程网络库 Acceptor TcpServer TcpConnecti ...
- muduo网络库学习(三)定时器TimerQueue的设计
Linux下用于获取当前时间的函数有 time(2) / time_t (秒) ftime(3) / struct timeb (毫秒) gettimeofday(2) / struct timeva ...
- 新书预告:《Linux 多线程服务端编程——使用 muduo C++ 网络库》
看完了 W. Richard Stevens 的传世经典<UNIX 网络编程>, 能照着例子用 Sockets API 编写 echo 服务, 却仍然对稍微复杂一点的网络编程任务感到无从下 ...
- 开源免费的C/C++网络库(c/c++ sockets library)
(1)ACE 庞大.复杂,适合大型项目.开源.免费,不依赖第三方库,支持跨平台. http://www.cs.wustl.edu/~schmidt/ACE.html (2)Asio Asio基于Boo ...
- 网易云音乐网络库跨平台化实践
导读: 2021年10月21日,「QCon 全球软件开发大会」在上海举办,网易智企技术 VP 陈功作为出品人发起了「AI 时代下的融合通信技术」专场,邀请到网易云信.网易音视频实验室.网易云音乐的技术 ...
最新文章
- 前端使用js发起http请求的几种方法
- Microsoft Expression Blend 4 下载地址
- Pentium Pro架构/流水线及其优化 (2) - 指令流水线 存储子系统详解
- 浅谈String str = 和 new String()的区别
- AngularJs学习笔记0——前言
- Java项目部署到云服务器最简单的方法
- 如何将本机的的git仓库提交到gitbub中
- python中幂运算_python 计算幂
- Oracle event px,oracle wait event:PX Deq Credit: send blkd
- 《爱上单片机》读后感——5年后终于了解什么是单片机
- 红外数据集 | 收集OTCBVS、KAIST、FLIR红外图像数据
- python求线段长度_如何用python求线段长度
- wannier拟合能带总是拟合不上_中科大PRL:面内磁化的本征量子反常霍尔效应:搜索规则和材料预测...
- Java实例教程(上)
- mfc 子窗口 跟随 主窗口
- 数字信号处理matlab相关实验
- Add/SubtractWorkingDaystoaDate_SAP刘梦_新浪博客
- Codeforces Round 361 div2
- java上传文件到七牛_java 上传文件到七牛云
- 【青梅快讯】Greenplum 最新版本6.20.3已正式发布
热门文章
- CC++刚開始学习的人编程教程(9) Windows8.1安装VS2013并捆绑QT与编程助手
- 可惜Java中没有yield return
- CMD-NET命令详解、NET命令大全(转)
- nstruts2.0发布前奏---浅谈struts和依赖注入在项目中的应用
- Struts1之Action小结
- 关于自然语言处理,有一本通关手册待接收
- ios nstimer实现延时_IOS_IOS开发代码分享之用nstimer实现倒计时功能,用nstimer实现倒计时功能,废话 - phpStudy...
- 读写分离mysql数据库mariadb_MariaDB数据库读写分离实现(一):mysql-proxy的使用
- MySQL高级 - 内存优化 - MyISAM内存优化
- 执行引擎(Query Execution Engine),返回结果