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 DEBUG
config.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.generalServer
request.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, // default
kXMRequestSerializerJSON = 1,
kXMRequestSerializerPlist = 2,
};
typedef NS_ENUM(NSInteger, XMResponseSerializerType) {
kXMResponseSerializerRAW = 0,
kXMResponseSerializerJSON = 1, // default
kXMResponseSerializerPlist = 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 request1
XMRequest *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
则是核心类的声明和实现,具体的代码结构如下图所示:
待完善
- 支持断点下载
- 支持网络层缓存
- 兼容测试支持 tvOS/watchOS/OS X
- 更加强大的自定义模型转换
- 实现一套可扩展的插件机制,便于 XMNetworking 增加新功能
作者
贡献者
许可证
XMNetworking 使用 MIT 许可证,详情见 LICENSE 文件。
网友评论
我能说用了这个更新要在主线程的操作都要自己来么??
这里面怎么写能不能给一个例子啊?
}