第三方框架 | AFNetworking源码解析(1) 使用（翻译）

AFNetworking 是一个为iOS, macOS, watchOS, 和 tvOS 提供的令人愉快网络库。它构建在 Foundation URL Loading System之上，拓展了内置到 Cocoa 中的强大高级的网络抽象。它拥有设计良好的模块化结构和功能丰富的API，使用起来很愉快。

然而，也许最重要的特性是每天使用和贡献AFNetworking的开发者社区。AFNetworking为iPhone、iPad和Mac上一些最流行、最受好评的应用程序提供了动力。

如何开始

---

• 下载 AFNetworking 并试用包含的Mac和iPhone示例应用
• 阅读入门指南，常见问题，或维基上的其他文章
• 查看 文档 以全面了解 AFNetworking 中可以使用的 API
• 阅读 AFNetworking 3.0 迁移指南 以了解2.0体系结构的变化概况

交流

---

• 如需 帮助，使用 Stack Overflow. (Tag 'afnetworking')
• 若想 问一个一般性问题，请使用 Stack Overflow
• 若是你 发现了bug，并能够提供可靠的可以复现的步骤,可以提一个 issue
• 若是你 有一个功能请求，可以提一个 issue
• 若是你 想贡献，提交一个 pull request

安装

---

AFNetworking 支持多种安装方法

使用 CocoaPods 安装

---

CocoaPods(http://cocoapods.org) 是 Objective-C 的依赖管理器，它自动化并简化了在项目中使用第三方库(如 AFNetworking )的过程。有关更多信息，请参阅入门指南。您可以使用以下命令安装：

$ gem install cocoapods

Podfile

使用 CocoaPods 集成 AFNetworking 到 Xcode 项目, 在你的 Podfile 文件中指定：

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'

target 'TargetName' do
pod 'AFNetworking', '~> 3.0'
end

然后, 运行以下命令:

$ pod install

使用 Carthage 安装

Carthage 是一个分散依赖管理器，可以构建你自己的依赖项并提供二进制框架。

你可以使用 Homebrew 命令安装 Carthage：

$ brew update
$ brew install carthage

使用 Carthage 集成 AFNetworking 到你的 Xcode 项目中，在你的 Cartfile 文件中指定：

github "AFNetworking/AFNetworking" ~> 3.0

运行 carthage 来构建框架并将构建好的 AFNetworking.framework 文件拖拽到你的 Xcode 项目中。

版本要求

AFNetworking Version	Minimum iOS Target	Minimum macOS Target	Minimum watchOS Target	Minimum tvOS Target	注意
3.x	iOS 7	OS X 10.9	watchOS 2.0	tvOS 9.0	Xcode 7+ is required. NSURLConnectionOperation support has been removed.
2.6 -> 2.6.3	iOS 7	OS X 10.9	watchOS 2.0	n/a	Xcode 7+ is required.
2.0 -> 2.5.4	iOS 6	OS X 10.8	n/a	n/a	Xcode 5+ is required. NSURLSession subspec requires iOS 7 or OS X 10.9.
1.x	iOS 5	Mac OS X 10.7	n/a	n/a
0.10.x	iOS 4	Mac OS X 10.6	n/a	n/a

(macOS 项目必须支持 64-bit with modern Cocoa runtime).

体系结构

---

NSURLSession

• AFURLSessionManager
• AFHTTPSessionManager

Serialization

• • AFHTTPRequestSerializer
  • AFJSONRequestSerializer
  • AFPropertyListRequestSerializer
• • AFHTTPResponseSerializer
  • AFJSONResponseSerializer
  • AFXMLParserResponseSerializer
  • AFXMLDocumentResponseSerializer (macOS)
  • AFPropertyListResponseSerializer
  • AFImageResponseSerializer
  • AFCompoundResponseSerializer

额外功能

• AFSecurityPolicy
• AFNetworkReachabilityManager

使用

---

AFURLSessionManager

AFURLSessionManager 基于指定 NSURLSessionConfiguration 对象创建和管理一个 NSURLSession 对象，并遵循了 ，，，和 协议。

创建一个下载任务

NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];
AFURLSessionManager *manager = [[AFURLSessionManager alloc] initWithSessionConfiguration:configuration];

NSURL *URL = [NSURL URLWithString:@"http://example.com/download.zip"];
NSURLRequest *request = [NSURLRequest requestWithURL:URL];

NSURLSessionDownloadTask *downloadTask = [manager downloadTaskWithRequest:request progress:nil destination:^NSURL *(NSURL *targetPath, NSURLResponse *response) {
    NSURL *documentsDirectoryURL = [[NSFileManager defaultManager] URLForDirectory:NSDocumentDirectory inDomain:NSUserDomainMask appropriateForURL:nil create:NO error:nil];
    return [documentsDirectoryURL URLByAppendingPathComponent:[response suggestedFilename]];
} completionHandler:^(NSURLResponse *response, NSURL *filePath, NSError *error) {
    NSLog(@"File downloaded to: %@", filePath);
}];
[downloadTask resume];

创建一个上传任务

NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];
AFURLSessionManager *manager = [[AFURLSessionManager alloc] initWithSessionConfiguration:configuration];

NSURL *URL = [NSURL URLWithString:@"http://example.com/upload"];
NSURLRequest *request = [NSURLRequest requestWithURL:URL];

NSURL *filePath = [NSURL fileURLWithPath:@"file://path/to/image.png"];
NSURLSessionUploadTask *uploadTask = [manager uploadTaskWithRequest:request fromFile:filePath progress:nil completionHandler:^(NSURLResponse *response, id responseObject, NSError *error) {
    if (error) {
        NSLog(@"Error: %@", error);
    } else {
        NSLog(@"Success: %@ %@", response, responseObject);
    }
}];
[uploadTask resume];

为多部分请求创建上传任务，并添加进度

NSMutableURLRequest *request = [[AFHTTPRequestSerializer serializer] multipartFormRequestWithMethod:@"POST" URLString:@"http://example.com/upload" parameters:nil constructingBodyWithBlock:^(id formData) {
        [formData appendPartWithFileURL:[NSURL fileURLWithPath:@"file://path/to/image.jpg"] name:@"file" fileName:@"filename.jpg" mimeType:@"image/jpeg" error:nil];
    } error:nil];

AFURLSessionManager *manager = [[AFURLSessionManager alloc] initWithSessionConfiguration:[NSURLSessionConfiguration defaultSessionConfiguration]];

NSURLSessionUploadTask *uploadTask;
uploadTask = [manager
              uploadTaskWithStreamedRequest:request
              progress:^(NSProgress * _Nonnull uploadProgress) {
                  // This is not called back on the main queue.
                  // You are responsible for dispatching to the main queue for UI updates
                  dispatch_async(dispatch_get_main_queue(), ^{
                      //Update the progress view
                      [progressView setProgress:uploadProgress.fractionCompleted];
                  });
              }
              completionHandler:^(NSURLResponse * _Nonnull response, id  _Nullable responseObject, NSError * _Nullable error) {
                  if (error) {
                      NSLog(@"Error: %@", error);
                  } else {
                      NSLog(@"%@ %@", response, responseObject);
                  }
              }];

[uploadTask resume];

创建一个数据请求任务

NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];
AFURLSessionManager *manager = [[AFURLSessionManager alloc] initWithSessionConfiguration:configuration];

NSURL *URL = [NSURL URLWithString:@"http://httpbin.org/get"];
NSURLRequest *request = [NSURLRequest requestWithURL:URL];

NSURLSessionDataTask *dataTask = [manager dataTaskWithRequest:request completionHandler:^(NSURLResponse *response, id responseObject, NSError *error) {
    if (error) {
        NSLog(@"Error: %@", error);
    } else {
        NSLog(@"%@ %@", response, responseObject);
    }
}];
[dataTask resume];

---

请求序列化器

请求序列化器通过 URL 字符串和编码参数为查询字符串或HTTP body创建 GET 或 POST 请求。

NSString *URLString = @"http://example.com";
NSDictionary *parameters = @{@"foo": @"bar", @"baz": @[@1, @2, @3]};

查询字符串参数编码

[[AFHTTPRequestSerializer serializer] requestWithMethod:@"GET" URLString:URLString parameters:parameters error:nil];

GET http://example.com?foo=bar&baz[]=1&baz[]=2&baz[]=3

URL 形式参数编码

[[AFHTTPRequestSerializer serializer] requestWithMethod:@"POST" URLString:URLString parameters:parameters error:nil];

POST http://example.com/
Content-Type: application/x-www-form-urlencoded

foo=bar&baz[]=1&baz[]=2&baz[]=3

JSON 参数编码

[[AFJSONRequestSerializer serializer] requestWithMethod:@"POST" URLString:URLString parameters:parameters error:nil];

POST http://example.com/
Content-Type: application/json

{"foo": "bar", "baz": [1,2,3]}

---

网络状态检测器

AFNetworkReachabilityManager 用来监控域，还包括 WWAN 和 WiFi 网络地址访问状态。

• 不使用检测器来确定是否应该发送原始请求。
  • 你应该试着发送它。
• 您可以使用检测器来确定何时应该自动重试请求。
  • 尽管它可能仍然失败，但是连接可用的检测器通知是重试的好时机。
• 网络检测器是一个有用的工具，用于确定请求可能失败的原因。
  • 在网络请求失败后，告诉用户他们离线比给他们一个更技术性但更准确的错误要好，比如“请求超时”。
    参见 WWDC 2012 session 706, "Networking Best Practices.".

网络监测器单例

[[AFNetworkReachabilityManager sharedManager] setReachabilityStatusChangeBlock:^(AFNetworkReachabilityStatus status) {
    NSLog(@"Reachability: %@", AFStringFromNetworkReachabilityStatus(status));
}];

[[AFNetworkReachabilityManager sharedManager] startMonitoring];

---

安全策略

AFSecurityPolicy 根据固定的X.509证书和公钥评估服务器信任，而不是安全连接。

在应用程序中添加固定的 SSL 证书有助于防止中间人攻击和其他漏洞。强烈建议处理敏感客户数据或财务信息的应用程序通过配置和启用 SSL 固定的 HTTPS 连接路由所有通信。

允许使用无效 SSL 证书

AFHTTPSessionManager *manager = [AFHTTPSessionManager manager];
manager.securityPolicy.allowInvalidCertificates = YES; // not recommended for production

---

单元测试

AFNetworking 包括测试子目录中的一组单元测试。这些测试可以简单地在您想要测试的平台框架上执行测试操作。

关于作者

AFNetworking 由 Alamofire软件基金会拥有和维护。

AFNetworking 的 logo 是由(http://www.alandefbaugh.com/)设计的。

最重要的是，感谢AFNetworking越来越多的贡献者.

安全信息披露

如果你确信自己发现了 AFNetworking 存在安全漏洞，你应该尽快发送邮件到 [email protected] 。请不要把它公布到问题追踪器上。

证书

AFNetworking 是在麻省理工学院许可(MIT license)下发布的。详情请参阅 许可证。