目的

RequestUtils是一组分类方法集合，旨在简化在Cocoa中进行HTTP请求构建和操作的流程。它通过一些额外的实用方法扩展了NSString、NSURL和NSURLRequest，这些方法被遗漏在标准API中了。

支持的操作系统和SDK版本

• 支持的构建目标 - iOS 9.2 / Mac OS 10.11 (Xcode 7.2, Apple LLVM编译器7.1)
• 最早支持的部署目标 - iOS 7.1 / Mac OS 10.10
• 最早兼容的部署目标 - iOS 4.3 / Mac OS 10.6.8

注意：'支持'表示库与该版本进行了测试。'兼容'表示库应该在该iOS版本上工作（即它不依赖于任何不可用的SDK功能），但不再对其兼容性进行测试，可能需要调整或修复错误才能正确运行。

ARC兼容性

从版本1.1开始，RequestUtils需要ARC。如果您想在非ARC项目中使用RequestUtils，只需将-fobjc-arc编译器标志添加到RequestUtils.m类文件中。要做到这一点，请转到目标设置中的构建阶段标签，在编译源文件组中打开编译源文件，双击列表中的RequestUtils.m，然后在弹出菜单中键入-fobjc-arc。

如果您想将整个项目转换为ARC，请在RequestUtils.m中取消注释#error行，然后在Xcode中运行编辑>重构>将转换为Objective-C ARC... 工具，并确保所有希望使用ARC的文件（包括RequestUtils.m）都被选中。

线程安全性

所有RequestUtils方法都可以在多个线程上安全地并发使用。

安装

要在一个应用中使用RequestUtils分类，只需将RequestUtils.h和.m文件（不需要示例文件和资源）拖动到您的项目中，并将头文件导入任何希望使用RequestUtils功能的类中，或者将其包含在prefix.pch文件中以在项目中全局使用。

NSString扩展

RequestUtils通过以下方法扩展了NSString：

@property(nonatomic, readonly) NSString *URLEncodedString;

这是一种将字符串进行URL编码的方法，以确保它可以安全地用于URL路径或查询参数中。这种方法与标准的stringByAddingPercentEscapesUsingEncoding:方法不同，因为后者只是确保字符串中不包含无效的字符，但不会对可以在URL中使用但不宜在查询字符串参数或路径组件中使用（例如，"?"、"&"）的字符进行编码。

- (NSString *)URLDecodedString:(BOOL)decodePlusAsSpace;

此方法通过将所有百分号转义序列替换为其原始字符来反转URLEncodedString的影响。内部使用stringByReplacingPercentEscapesUsingEncoding:，使用NSUTF8StringEncoding。参数decodePlusAsSpace会导致"+"字符被转换为空格，如果参数是通过网页表单生成的，这非常有用。

- (NSString *)stringByAppendingURLPathExtension:(NSString *)extension;

NSString有一个有用的方法stringByAppendingPathExtension:，可以将路径扩展名添加到字符串的末尾，并以点正确分隔。不幸的是，《stringByAppendingPathExtension:方法不是URL感知的，并且在不添加路径时错误地从URL中删除了双斜杠//。stringByAppendingURLPathExtension:更智能，不仅避免了从URL方案中删除，而且还会正确在URL查询或片段字符串之前插入路径扩展名。

@property(nonatomic, readonly) NSString *stringByDeletingURLPathExtension;

这是stringByDeletingURLPathExtension方法的URL感知版本。它将删除路径的最后一部分，而不会破坏查询或片段字符串，或破坏//（如果存在）。

@property(nonatomic, readonly) NSString *URLPathExtension;

这是pathExtension方法的URL感知版本。它将返回路径文件扩展名，不包括查询或片段字符串（如果存在）。

- (NSString *)stringByAppendingURLPathComponent:(NSString *)str;

NSString有一个有用的方法stringByAppendingPathComponent:，可以将路径组件添加到字符串的末尾，同时正确地添加分隔符/并避免在路径组件已经包含分隔符的情况下重复分隔符。不幸的是，《stringByAppendingPathComponent:方法不是URL感知的，并且在不添加路径时错误地从URL中删除双斜杠//。stringByAppendingURLPathComponent:更智能，不仅避免了从URL方案中删除//，而且还会正确在URL查询或片段字符串之前插入路径组件。

@property(nonatomic, readonly) NSString *stringByDeletingLastURLPathComponent;

这是stringByDeletingLastPathComponent方法的URL感知版本。它将删除路径的最后一部分，而不会破坏查询或片段字符串，或破坏//（如果存在）。

@property(nonatomic, readonly) NSString *lastURLPathComponent;

这是lastPathComponent方法的URL感知版本。它将返回路径的最后一部分，不包括查询或片段字符串（如果存在）。

+ (NSString *)URLQueryWithParameters:(NSDictionary *)parameters;

此方法从键和值的字典中生成URL查询字符串。字典中的值可以是单个值，例如字符串或数字，也可以是值数组，在这种情况下，默认情况下将使用数组的最后一个值。字典中的所有键和值都将自动进行URL编码。有关如何处理参数数组的更多选项，请参阅以下内容。

+ (NSString *)URLQueryWithParameters:(NSDictionary *)parameters options:(URLQueryOptions)options;

此方法从键和值的字典中生成URL查询字符串，但提供了一个额外的options参数来控制如何处理参数数组。字典中的所有键和值都将自动进行URL编码。有关选项的讨论，请参阅以下内容URLQueryOptions。

@property(nonatomic, readonly) NSString *URLQuery;

此方法尝试在字符串中查找和返回URL查询字符串。它与NSURL的query方法类似，但与部分URL/URI或非标准结构的URL/URI一起使用时效果更好。

@property(nonatomic, readonly) NSString *stringByDeletingURLQuery;

此方法查找并删除字符串中的URL查询。它了解URL片段/哈希，如果存在，将留下URL片段不变。

- (NSString *)stringByReplacingURLQueryWithQuery:(NSString *)query

替换当前查询字符串（如果存在）为指定的查询字符串。将空值或空字符串作为查询参数传递与调用 stringByDeletingURLQuery 相同；

- (NSString *)stringByAppendingURLQuery:(NSString *)query;

此方法将 URL 查询追加到字符串。它可感知 URL 片段/哈希，如果有 #，则会将查询字符串插入其前。如果字符串中已经存在查询字符串，则两个字符串将会连接起来，不考虑重复参数，但如果需要，将插入 &。有关合并查询字符串更多的选项，请参阅下面；

- (NSString *)stringByMergingURLQuery:(NSString *)query;

此方法将 URL 查询追加到字符串，合并任何重复值。重复查询参数键将被遇到的最后该键值替代。关于合并选项的更多信息，请参阅下面；

- (NSString *)stringByMergingURLQuery:(NSString *)query options:(URLQueryOptions)options;

此方法将 URL 查询追加到字符串，合并任何重复值。默认情况下，重复的查询参数将用该键遇到的最後值替换，但您可以使用 options 参数来覆盖该行为。关于选项的讨论请查阅下面的 URLQueryOptions；

@property(nonatomic, readonly) NSDictionary *URLQueryParameters;

此方法尝试在字符串中查找查询字符串，并将其分割为键/值对的字典。每个键和值都将进行 URL 解码。如果遇到重复参数键，则使用该键遇到的最後值。若要覆盖此行为，请使用 URLQueryParametersWithOptions:；

- (NSDictionary *)URLQueryParametersWithOptions:(URLQueryOptions)options;

此方法尝试在字符串中查找查询字符串，并将其分割为键/值对的字典。每个键和值都将进行 URL 解码。options 参数控制如何处理重复参数。有关选项的讨论请查阅下面的 URLQueryOptions；

@property(nonatomic, readonly) NSString *URLFragment;

此方法返回字符串的 URL 片段标识符或哈希部分。它与NSURL的fragment方法类似，但更适用于处理部分URL/URI或具有非标准结构的URL，例如特定方案。

@property(nonatomic, readonly) NSString *stringByDeletingURLFragment;

此方法寻找并从字符串中移除 URL 片段标识符（如果存在）。

- (NSString *)stringByAppendingURLFragment:(NSString *)fragment;

此方法将 URL 片段标识符追加到字符串。它也会将字符串正确连接到现有的片段标识符（如果存在）。不会分析片段结构或正确处理片段字符串内的路径连接。如果您需要这样操作，请在单独生成片段后再一次性设置它。

@property(nonatomic, readonly) NSURL *URLValue;

此方法将字符串转换为 URL。它类似于使用 [NSURL URLWithString:]，但有几点优点：1) 如果字符串为 nil，则不会抛出异常；2) 会自动检测字符串是否为文件路径，并将使用 [NSURL fileURLWithString:] 代替 [NSURL URLWithString:]，从而消除了常见的错误。

- (NSURL *)URLValueRelativeToURL:(NSURL *)baseURL;

此方法将字符串转换为 URL。它类似于使用 [NSURL URLWithString:relativeToURL]，但如果字符串为 nil，则不会抛出异常。

@property(nonatomic, readonly) NSString *base64EncodedString;

将字符串作为 UTF8 数据编码，然后作为无包装（行中断）的 base-64 编码字符串编码。有关更高级的 base 64 编码选项，请查看我的 Base64 库（https://github.com/nicklockwood/Base64）。

@property(nonatomic, readonly) NSString *base64DecodedString;

将字符串视为 base-64 编码字符串，并返回一个自动释放的 NSString 对象，包含使用 UTF8 编码的解释的解码数据。字符串中的任何非 base-64 字符都将被忽略，因此可以使用包含换行符或其他分隔符的字符串。有关更高级的 base 64 解码选项，请查看我的 Base64 库（https://github.com/nicklockwood/Base64）。

NSURL 扩展

RequestUtils 扩展了 NSURL 以下方法

+ (NSURL *)URLWithComponents:(NSDictionary *)components;

该函数从提供的组件字典构建URL。该字典可以包含以下任何一个或所有项：方案，主机，端口，用户，密码，路径，参数字符串，查询，片段（所有这些值都定义了一组常量）。所有值都是可选的，并且方法将根据提供的值尝试构建尽可能多的URL。所有提供的值都应该是NSString，除了URLQueryComponent，它可以是一个NSString或查询参数的NSDictionary。

@property(nonatomic, readonly) NSDictionary *components;

返回包含以下任何一个或所有项的URL组件字典：方案，主机，端口，用户，密码，路径，参数字符串，查询，片段。

- (NSURL *)URLWithScheme:(NSString *)scheme;

设置或替换当前的URL方案为提供值。

- (NSURL *)URLWithHost:(NSString *)host;

设置或替换当前的URL主机为提供值。

- (NSURL *)URLWithPort:(NSString *)port;

设置或替换当前的URL端口为提供值。

- (NSURL *)URLWithUser:(NSString *)user;

设置或替换当前的URL用户为提供值。

- (NSURL *)URLWithPassword:(NSString *)password;

设置或替换当前的URL密码为提供值。

- (NSURL *)URLWithPath:(NSString *)path;

设置或替换当前的URL路径为提供值。

- (NSURL *)URLWithParameterString:(NSString *)parameterString;

设置或替换当前的URL参数字符串为提供值。

- (NSURL *)URLWithQuery:(NSString *)query;

设置或替换当前的URL查询为提供值。

- (NSURL *)URLWithFragment:(NSString *)fragment;

设置或替换当前的URL片段为提供值。

NSURLRequest 扩展

RequestUtils 扩展了NSURLRequest，包含了以下方法

+ (id)HTTPRequestWithURL:(NSURL *)URL method:(NSString *)method parameters:(NSDictionary *)parameters;

使用指定的URL、HTTP方法和参数创建一个新的、自动释放的NSURLRequest。对于GET请求，参数将被编码到查询字符串中；对于其他所有方法，参数将被编码到POST正文中。

+ (id)GETRequestWithURL:(NSURL *)URL parameters:(NSDictionary *)parameters;

使用GET方法和指定的URL及参数创建一个新的、自动释放的NSURLRequest。参数会被URL编码并设置为请求URL的查询字符串。如果URL已经包含查询字符串，则传递的参数将根据NSString stringByMergingURLQuery:扩展方法的使用规则附加到现有查询上。

+ (id)POSTRequestWithURL:(NSURL *)URL parameters:(NSDictionary *)parameters;

使用POST方法和指定的URL及参数创建一个新的、自动释放的NSURLRequest。参数会被URL编码并设置为请求的正文。

@property(nonatomic, readonly) NSDictionary *GETParameters;

返回请求的GET（查询字符串）参数作为一个字典。

@property(nonatomic, readonly) NSDictionary *POSTParameters;

返回请求的POST（请求正文）参数作为一个字典。

@property(nonatomic, readonly) NSString *HTTPBasicAuthUser;

返回HTTP基本认证用户。如果请求有一个Authorization首部，则使用该首部来获取用户；否则如果URL本身指定了一个用户，则使用该用户。

@property(nonatomic, readonly) NSString *HTTPBasicAuthPassword;

返回HTTP基本认证密码。如果请求有一个Authorization首部，则使用该首部来获取密码；否则如果URL本身指定了一个密码，则使用该密码。

NSMutableURLRequest 扩展

RequestUtils 扩展了NSMutableURLRequest，包含了以下方法

@property(nonatomic, copy) NSDictionary *GETParameters;

- (void)setGETParameters:(NSDictionary *)parameters options:(URLQueryOptions)options

此方法使用字典设置请求的GET参数。参数会被URL编码并设置为请求URL的查询字符串。任何现有的查询字符串参数将被新的值替换。可选的options参数允许您控制查询参数的序列化方式（有关详细信息，请参阅下面的URLQueryOptions部分）。

- (void)addGETParameters:(NSDictionary *)parameters options:(URLQueryOptions)options

此方法与setGETParameters:方法类似，不同之处在于参数被合并到现有的请求参数中而不是替换它们。合并发生的规则由options参数控制（有关详细信息，请参阅下面的URLQueryOptions部分）。

@property(nonatomic, copy) NSDictionary *POSTParameters;

- (void)setPOSTParameters:(NSDictionary *)parameters options:(URLQueryOptions)options

此方法使用字典设置请求的POST参数。参数将被进行URL编码，并设置为请求的主体。所有当前请求主体的内容将被替换。可选的options参数允许您控制如何序列化POST参数（有关详细信息，请参阅下方的URLQueryOptions部分）。

- (void)addPOSTParameters:(NSDictionary *)parameters options:(URLQueryOptions)options

此方法类似于setPOSTParameters:方法，但是参数将被合并到现有的POST参数中，而不是替换它们。合并发生的规则由options参数控制（有关详细信息，请参阅下方的URLQueryOptions部分）。

- (void)setHTTPBasicAuthUser:(NSString *)user password:(NSString *)password;

此方法用于设置请求的HTTP基本认证用户名和密码。使用请求的Authorization头部来设置用户名和密码。

URLQueryOptions

查询字符串操作方法提供了一些选项，用于查询字符串的生成或解释。可以使用|（管道）或+（加号）运算符合并选项。但是，一些选项是互斥的，不应该合并使用。

URLQueryOptionDefault

如果没有指定其他选项，则是默认选项。当使用URLQueryWithParameters:从字典生成查询字符串时，这相当于URLQueryOptionUseArrays，意味着任何值数组将被展开为多个参数。

当使用URLQueryParameters将查询字符串解析为参数字典时，这相当于URLQueryOptionKeepLastValue，意味着在遇到重复的参数键时，将使用最后一个重复的值。

URLQueryOptionKeepLastValue

当使用URLQueryParameters将查询字符串解析为参数字典时，这是默认选项。当使用此选项且遇到重复参数键时，将使用最后一个重复的值。

当使用URLQueryWithParameters:options:从字典生成查询字符串时，如果为参数提供了值数组，此选项将仅使用最后一个值来构造查询字符串。

URLQueryOptionKeepFirstValue

当使用URLQueryParametersWithOptions:将查询字符串解析为参数字典时，如果遇到重复参数键，将使用有给定键的第一个遇到的值。

当使用URLQueryWithParameters:options:从字典生成查询字符串时，如果为参数提供了值数组，此选项将仅使用第一个值来构造查询字符串。

URLQueryOptionUseArrays

当使用URLQueryParametersWithOptions:将查询字符串解析为参数字典时，如果遇到重复参数键或键有"[]"数组后缀，将把值收集到数组中。因此，结果参数数组将包含数组和字符串值的混合，您在处理时需要添加代码来检查每个字典条目的类型。

当使用URLQueryWithParameters:options:从字典生成查询字符串时，如果为参数提供了值数组，则使用此选项将在查询字符串中为该键添加重复的参数。

URLQueryOptionAlwaysUseArrays

当使用URLQueryParametersWithOptions:将查询字符串解析为参数字典时，即使只有给定键的一个参数（在这种情况下数组将包含一个项目），每个字典条目也将被创建为数组。这种做法的优点是可以保证每个字典条目都是数组，从而避免在处理时需要添加代码来检查每个字典条目的类型。

当使用 URLQueryWithParameters:options: 从字典生成查询字符串时，此选项等同于 URLQueryOptionUseArrays，除非同时启用了 URLQueryOptionUseArraySyntax。如果启用了 URLQueryOptionUseArraySyntax，使用 URLQueryOptionUseArrays 意味着查询字符串中的每个键都将附加 "[]"，即使只有一个与之关联的值。这可能随后影响对这些参数的解释（即作为单项数组而不是字符串）。有关更多讨论，请参阅 URLQueryOptionUseArraySyntax。

URLQueryOptionUseArraySyntax

与之前的选项不同，它们是相互排斥的，URLQueryOptionUseArraySyntax 可以与 URLQueryOptionUseArrays 或 URLQueryOptionAlwaysUseArrays 结合使用以影响输出。当使用 URLQueryWithParameters:options: 从字典生成查询字符串时，设置此选项意味着任何具有多个值（或者如果使用 URLQueryOptionAlwaysUseArrays，则任何键）的键都将附加 "[]" 语法，以表明它是参数数组的一部分。

"[]" 键后缀不是 RFC 1808 URL 规范的官方部分，但它是一些流行的 Web 服务器平台（包括 PHP）中使用的一项现场标准，因此能够解释和/或以这种格式生成查询字符串可能会有所帮助。默认情况下，此选项是禁用的。

URLQueryOptionUseArraySyntax 在使用 URLQueryParameters: 方法解析查询字符串时没有影响。

URLQueryOptionSortKeys

URLQueryOptionSortKeys 选项可以与之前的任何选项结合使用。它在生成查询字符串时用于确保结果字符串中的键将按一致顺序（字母顺序）输出。在进行单元测试或对结果字符串进行加密散列时，这非常有用，其中您需要能够依赖顺序保持一致。

发行说明

版本 1.1.2

• 添加了可空性注解
• 添加了轻量级泛型注解
• 将获取器转换为只读属性
• 修复了 iOS9 中的弃用警告
• 将 watchOS 和 tvOS 添加到 Podspec

版本 1.1.1

• 修复了 Xcode 6.3 和 7.0 上的警告
• 移除了冗余的 [self description] 调用

版本 1.1

• 添加了 URLQueryOptionSortKeys 选项
• 现在需要 ARC

版本 1.0.4

• 修复了 -[NSURL URLWithPath:] 中的错误

版本 1.0.3

• 修复了当请求数字字典中的键或不是字符串的值时崩溃的错误
• 改进了测试覆盖率

版本 1.0.2

• 修复了 stringByAppendingURLQuery: 方法中的错误
• 更新为使用原生 base64 支持
• 现在符合 -Weverything 警告级别

版本 1.0.1

• 更新以支持 Xcode 4.6
• URLEncoding 现在可以优雅地处理非字符串值（例如 NSNumber）
• 修复了 stringByMergingURLQuery:options: 方法中的错误

版本 1.0

• 初始发布。