AFN源码阅读-AFURLResponseSerialization

AFURLResponseSerialization协议可以根据我们从服务器返回的响应信息中，将数据解码为更利于我们使用的对象形式。响应序列化程序还可以对传入的返回信息和数据执行验证。

比如，一个JSON的响应序列化可以检查acceptable status code(2XX范围内)和content type(application/json),从而将有效的JSON响应数据解码为对象。

 */
@protocol AFURLResponseSerialization 

/**
根据关联数据和具体响应信息解码为响应对象

 @param response 要处理的响应
 @param data 要被解码的数据
 @param error 解码响应的数据时发生的错误

 @return 根据具体的响应数据解码的对象
 */
- (nullable id)responseObjectForResponse:(nullable NSURLResponse *)response
                           data:(nullable NSData *)data
                          error:(NSError * _Nullable __autoreleasing *)error NS_SWIFT_NOTHROW;

@end

pragma mark - AFHTTPResponseSerializer

/**
AFHTTPResponseSerializer遵守AFURLRequestSerialization 和 AFURLResponseSerialization 协议，提供查询字符串/URL表单编码参数序列化和默认请求头的具体基本实现，以及响应状态代码和内容类型验证。

为了确保一致的默认行为，鼓励将AFHTTPResponseSerializer子类化来处理任何HTTP的请求和响应。
*/

@interface AFHTTPResponseSerializer : NSObject 

- (instancetype)init;

@property (nonatomic, assign) NSStringEncoding stringEncoding DEPRECATED_MSG_ATTRIBUTE("从不使用字符串编码。AFHTTPResponseSerializer只验证状态代码和内容类型，但不尝试以任何方式解码接收到的数据");

/**
    创建并返回一个带默认配置信息的序列化对象
 */
+ (instancetype)serializer;

///-----------------------------------------
/// @name Configuring Response Serialization
///-----------------------------------------

/**
响应的可接受HTTP状态代码。当为非“nil”时，响应的状态码如果未包含在集合中，那么在验证过程中将会发生错误。
 详情可见 http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
 */
@property (nonatomic, copy, nullable) NSIndexSet *acceptableStatusCodes;

/**
响应的可接受的MIME类型。当为非“nil”时，如果`Content-Type` 的MIME不与集合相交，那么在处理响应的验证过程中将会出错。
 */
@property (nonatomic, copy, nullable) NSSet  *acceptableContentTypes;

/**
验证指定的响应和数据。

 In its base implementation, this method checks for an acceptable status code and content type. Subclasses may wish to add other domain-specific checks.
在其基本实现中，此方法检查可接受的状态码和内容类型。子类可能希望添加其他特定域的检查。

 @param response 进行验证的响应.
 @param data 响应的关联数据.
 @param error 验证响应时发生的错误

 @return 如果验证有效则返回`YES`否则返回`NO`.
 */
- (BOOL)validateResponse:(nullable NSHTTPURLResponse *)response
                    data:(nullable NSData *)data
                   error:(NSError * _Nullable __autoreleasing *)error;

@end

pragma mark - AFJSONResponseSerializer

AFJSONResponseSerializer 是AFHTTPResponseSerializer的子类用来验证和解码JSON响应。

默认情况下，“ AFJSONResponseSerializer”接受以下MIME类型，包括官方标准、“application/json”以及其他常用类型：

• application/json
• text/json
• text/javascript

在RFC7159第8.1节中，它指出JSON文本需要以UTF-8、UTF-16或UTF-32编码，默认编码为UTF-8。NSJSONSerialization为规范中列出的所有编码提供支持，并建议使用utf-8以提高效率。使用不支持的编码将导致序列化错误。有关详细信息，请参阅“ NSJSONSerialization”文档。

@interface AFJSONResponseSerializer : AFHTTPResponseSerializer

- (instancetype)init;

/**
Options for reading the response JSON data and creating the Foundation objects. For possible values, see the `NSJSONSerialization` documentation section "NSJSONReadingOptions". `0` by default.
读取响应JSON数据并创建基础对象的选项。有关可能的值，请参阅“ NSJSONSerialization”文档部分“ NSJSONReadingOptions”。默认为`0`
*/
@property (nonatomic, assign) NSJSONReadingOptions readingOptions;

/**
是否移除响应JSON中值为 `NSNull`的键，默认为`NO`
*/
@property (nonatomic, assign) BOOL removesKeysWithNullValues;

/**
   创建并返回一个JSON具有指定读写选项的序列化对象

@param readingOptions 指定的JSON读取选项。
*/
+ (instancetype)serializerWithReadingOptions:(NSJSONReadingOptions)readingOptions;

@end

pragma mark - AFXMLParserResponseSerializer

AFXMLParserResponseSerializer是AFHTTPResponseSerializer的一个子类，用于验证XML响应并将其解码为NSXMLParser对象。

默认情况下，AFXMLParserResponseSerializer接受以下MIME类型，包括官方标准、application/xml以及其他常用类型：

• application/xml
• text/xml

@interface AFXMLParserResponseSerializer : AFHTTPResponseSerializer

@end

pragma mark - AFXMLDocumentResponseSerializer

AFXMLDocumentResponseSerializer是AFHTTPResponseSerializer的一个子类，用于验证XML响应并将其解码为NSXMLDocument对象。

默认情况下，AFXMLParserResponseSerializer接受以下MIME类型，包括官方标准、“application/xml”以及其他常用类型：

• application/xml
• text/xml

@interface AFXMLDocumentResponseSerializer : AFHTTPResponseSerializer

- (instancetype)init;

/**
专门用于'NSXMLDocument'对象的输入和输出选项。有关可能的值，请参阅“ NSXMLDocument”文档部分“输入和输出选项”。默认为`0`
 */
@property (nonatomic, assign) NSUInteger options;

/**
创建并返回一个具有指定选项的XML文件序列化对象

 @param mask  XML文件 选项.
 */
+ (instancetype)serializerWithXMLDocumentOptions:(NSUInteger)mask;

@end

pragma mark - AFPropertyListResponseSerializer

AFPropertyListResponseSerializer是AFHTTPResponseSerializer的一个子类，用于验证XML响应并将其解码为NSXMLDocument对象。

默认情况下，AFXMLParserResponseSerializer接受以下MIME类型：

• application/x-plist

@interface AFPropertyListResponseSerializer : AFHTTPResponseSerializer

- (instancetype)init;

/**
属性列表格式。`NSPropertyListFormat`中描述了可能的值。
*/
@property (nonatomic, assign) NSPropertyListFormat format;

/**
属性列表读取选项，`NSPropertyListMutabilityOptions `中描述了可能的值。
*/
@property (nonatomic, assign) NSPropertyListReadOptions readOptions;

/**
创建并返回一个具有指定格式和读写选项的属性列表序列化对象

@param format 属性列表格式
@param readOptions 属性列表读取选项
*/
+ (instancetype)serializerWithFormat:(NSPropertyListFormat)format
                        readOptions:(NSPropertyListReadOptions)readOptions;

@end

pragma mark - AFImageResponseSerializer

AFImageResponseSerializer是AFHTTPResponseSerializer的一个子类，用于验证和解码图像响应。

默认情况下，AFImageResponseSerializer 可接受以下MIME类型
，这些类型对应UIImage或NSImage支持的图像格式：

• image/tiff
• image/jpeg
• image/gif
• image/png
• image/ico
• image/x-icon
• image/bmp
• image/x-bmp
• image/x-xbitmap
• image/x-win-bitmap

@interface AFImageResponseSerializer : AFHTTPResponseSerializer

#if TARGET_OS_IOS || TARGET_OS_TV || TARGET_OS_WATCH
/**
解释图像数据以构造` responseImage`时使用的比例因子。将比例因子指定为1.0将导致图像的大小与基于像素的图像尺寸匹配。应用不同的比例因子会更改“大小”属性报告的图像大小。默认情况下，该值设置为主屏幕的比例值，例如，它自动缩放视网膜显示的图像。
 */
@property (nonatomic, assign) CGFloat imageScale;

/**
是否自动为压缩格式（如png或jpeg）填充响应图像数据。当与'`setCompletionBlockWithSuccess:failure:`'一起使用时，启用此选项可以显著提高iOS上的绘图性能，因为它允许在后台而不是在主线程上构建位图表示。默认为YES。
 */
@property (nonatomic, assign) BOOL automaticallyInflatesResponseImage;
#endif

@end

pragma mark - AFCompoundResponseSerializer

AFCompoundSerializer是AFHTTPResponseSerializer的一个子类，它将响应序列化委托给第一个AFHTTPResponseSerializer对象，该对象返回responseObjectforResponse:data:error:的对象，返回'AFHTTPResponseSerializer'的默认行为。这对于使用单个序列化程序支持多个潜在的服务器响应类型和结构非常有用。

@interface AFCompoundResponseSerializer : AFHTTPResponseSerializer

/**
    响应序列化组件
 */
@property (readonly, nonatomic, copy) NSArray > *responseSerializers;

/**
创建并返回由指定的响应序列化对象组成的复合序列化对象。

 @warning  指定的每个响应序列化对象都必须是“ AFHTTPResponseSerializer”的子类，并且能响应`-validateResponse:data:error:`。
 */
+ (instancetype)compoundSerializerWithResponseSerializers:(NSArray > *)responseSerializers;

@end

///----------------
/// @name Constants 一些名称常量
///----------------

/**

Error Domains

预定义了以下错误域。

• NSString * const AFURLResponseSerializationErrorDomain

Constants

AFURLResponseSerializationErrorDomain
AFURLResponseSerializer错误。AFURLResponseSerializationErrorDomain的错误代码与NSURLErrorDomain中的代码相对应。
*/
FOUNDATION_EXPORT NSString * const AFURLResponseSerializationErrorDomain;

/**

User info dictionary keys(用户信息字典Keys)

除了为NSError定义的键之外，这些键还可以存在于用户信息字典中。

• NSString * const AFNetworkingOperationFailingURLResponseErrorKey
• NSString * const AFNetworkingOperationFailingURLResponseDataErrorKey

Constants

AFNetworkingOperationFailingURLResponseErrorKey
相应的值是一个NSURLResponse，包含与错误关联的操作的响应。此键仅存在于AFURLResponseSerializationErrorDomain中。

AFNetworkingOperationFailingURLResponseDataErrorKey
相应的值是一个NSData，其中包含与错误相关联的操作的原始数据。此密钥仅存在于AFURLResponseSerializationErrorDomain中。
*/
FOUNDATION_EXPORT NSString * const AFNetworkingOperationFailingURLResponseErrorKey;

FOUNDATION_EXPORT NSString * const AFNetworkingOperationFailingURLResponseDataErrorKey;