前言
HZNetwork是HZExtend框架中的一个网络组件，它是基于AFNetworking的一个封装，因此它支持IOS, OS X, watchOS, and tvOS. 它将每个请求都视为一个task，开发者可以为task配置网络请求所需要的一些参数，在task执行的过程中可以从其获取缓存数据，执行成功后可以从其获取远程数据。并且HZNetwork提供了缓存数据的接口，你可以自定义如何进行数据缓存。
介绍
- 支持HTTP(S)请求和REST API
- 支持公共请求头和baseURL配置
- 支持自定义请求成功判断
安装
添加 pod 'HZNetwork' 到Podfile文件里，然后运行pod install
使用
一.基础配置
1.在使用HZNetwork之前需要通过HZNetworkConfig单例进行网络请求的基础参数配置。
[[HZNetworkConfig sharedConfig] setupBaseURL:@"https://api.example.com" codeKeyPath:@"code" msgKeyPath:@"msg" userAgent:@"HZNetwork Example" rightCode:0];
该参数配置对应的响应格式为{code:0,data:{....},msg:"success"}, code为0表示task执行成功，否则为执行失败，msg字段中的数据可以通过task的message只读属性获取。当然你也可以通过task的baseURL属性，对一些特别的task的进行单独的设置。
2.配置task的公共请求头
[[HZNetworkConfig sharedConfig] addDefaultHeaderFields:@{@"http-header-field":@"value"}];
也可以通过task的方法进行特别的设置
[task setValue:@"value" forHeaderField:@"field"];
3.注册缓存处理者
[[HZNetworkConfig sharedConfig] registerCacheHandler:[[HZNetworkCacheHandler alloc] init]];
缓存处理者需要实现HZNetworkCache协议来对远程数据进行存取
- (void)setCache:(id)cache forKey:(NSString *)key
{
//cache
}
- (id)cacheForKey:(NSString *)key
{
//get
}
注意：如果想要对远程数据进行缓存，请确保task的cached值为YES来开启缓存。
4.设置默认开启task缓存
[HZNetworkConfig sharedConfig].taskShouldCache = YES;
设置之后所有的task都会默认对远程数据进行缓存
二.Task
1.创建GET/POST task
HZSessionTask *task = [HZSessionTask taskWithMethod:@"GET" path:@"/user/info" params:@{@"type":@6} delegate:self taskIdentifier:@"/user/info"];
//设置task发送后回调
task.taskDidSendBlock = ^(HZSessionTask * _Nonnull task) {
//获取缓存数据
if (task.cacheImportState == HZSessionTaskCacheImportStateSuccess) {
NSLog(@"%@",task.responseObject);
}
}
//启动task并设置完成回调
[task startWithCompletion:^(HZSessionTask * _Nonnull task) {
if (task.state == HZSessionTaskStateSuccess) {
//获取远程数据
NSLog(@"%@",task.responseObject);
}else {
//展示错误信息
NSLog(@"tip:%@ error:%@",task.message, task.error);
}
}];
2.创建REST task
//task的absoluteURL为 https://api.example.com/user/1
HZSessionTask *task = [HZSessionTask taskWithMethod:@"POST" path:@"/user" pathValues:@[@"1"] delegate:self taskIdentifier:@"/user"];
//设置参数(懒加载)
[task.params setObject:@"value" forKey:@"param"];
3.创建upload task
HZSessionTask *uploadTask = [HZSessionTask uploadTaskWithPath:@"/user/avatar" params:@{@"id":@"3"} delegate:self taskIdentifier:@"/user/avatar"];
//设置文件参数
uploadTask.fileParams = [NSMutableDictionary dictionaryWithDictionary:@{kHZFileMimeType:@"image/jpeg",kHZFileFormName:@"file",kHZFileURL:localPath}];
//设置上传回调
uploadTask.uploadProgressBlock = ^(HZSessionTask * _Nonnull task, NSProgress * _Nonnull progress) {
}
//启动task
[uploadTask start];
三.Task的状态
task的状态可以分为2类,一种表示请求状态，另外一种表示缓存导入状态
1.请求状态
typedef NS_ENUM(NSUInteger, HZSessionTaskState) { //The execution state of the task.
HZSessionTaskStateRunable = 0, //初始默认状态
HZSessionTaskStateRunning = 1, //请求中状态
HZSessionTaskStateCancel = 2, //被取消状态
HZSessionTaskStateSuccess = 3, //请求成功状态
HZSessionTaskStateFail = 4, //请求失败状态
};
@property(nonatomic, assign, readonly) HZSessionTaskState state;
一个task可以多次被执行，也就是说当请求结束时task最终会重新进入HZSessionTaskStateRunable状态。
2.缓存导入状态
typedef NS_ENUM(NSUInteger, HZSessionTaskCacheImportState) { //The importing state of cache.
HZSessionTaskCacheImportStateNone = 0, //初始默认状态
HZSessionTaskCacheImportStateSuccess = 1, //缓存导入成功状态
HZSessionTaskCacheImportStateFail = 2, //缓存导入失败状态，可能缓存不存在，也可能缓存只允许导入一次
};
@property(nonatomic, assign, readonly) HZSessionTaskCacheImportState cacheImportState;
默认情况下只对有效数据进行缓存，并且每个请求在多次执行的过程中只有在第一次执行时导入缓存，可以通过importCacheOnce属性进行设置每次都导入缓存。
四.回调
可以为task设置代理从而对回调事件进行处理
//请求完成时调用
- (void)taskDidCompleted:(HZSessionTask *)task;
//请求发送后调用
- (void)taskDidSend:(HZSessionTask *)task;
//请求取消后调用
- (void)taskDidCancel:(HZSessionTask *)task;
//请求将要被执行时调用，返回NO来拦截请求
- (BOOL)taskShouldStop:(HZSessionTask *)task stopMessage:(NSString *_Nullable __autoreleasing *_Nullable)message;
