前言

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;