在用 NSURLSession 或 NSURLConnection 發請求之前,你要先有一個 NSURLRequest 來描述這次請求,而伺服器回什麼,則封裝在 NSURLResponse 裡。這兩個類看起來樸素,但真正需要調的時候,能查得到屬性名稱就省下不少時間。
// 類方法建立預設請求:使用 NSURLRequestUseProtocolCachePolicy,超時 60 秒
+ (instancetype)requestWithURL:(NSURL *)URL;
// 是否支援安全編碼
+ (BOOL)supportsSecureCoding;
// 建立時可同時指定緩存策略與超時
+ (instancetype)requestWithURL:(NSURL *)URL
cachePolicy:(NSURLRequestCachePolicy)cachePolicy
timeoutInterval:(NSTimeInterval)timeoutInterval;
// init 版本,行為同上
- (instancetype)initWithURL:(NSURL *)URL;
- (instancetype)initWithURL:(NSURL *)URL
cachePolicy:(NSURLRequestCachePolicy)cachePolicy
timeoutInterval:(NSTimeInterval)timeoutInterval;
// 以下皆為只讀
@property (nullable, readonly, copy) NSURL *URL;
@property (readonly) NSURLRequestCachePolicy cachePolicy;
@property (readonly) NSTimeInterval timeoutInterval;
@property (nullable, readonly, copy) NSURL *mainDocumentURL;
@property (readonly) NSURLRequestNetworkServiceType networkServiceType;
@property (readonly) BOOL allowsCellularAccess;
緩存策略的枚舉值得單獨看一眼,它決定了「這次到底走不走本地緩存」:
typedef NS_ENUM(NSUInteger, NSURLRequestCachePolicy) {
NSURLRequestUseProtocolCachePolicy = 0, // 預設,遵循協議自身的緩存規則
NSURLRequestReloadIgnoringLocalCacheData = 1, // 忽略本地緩存,直接重新請求
NSURLRequestReloadIgnoringLocalAndRemoteCacheData = 4, // 未實作
NSURLRequestReloadIgnoringCacheData = NSURLRequestReloadIgnoringLocalCacheData,
NSURLRequestReturnCacheDataElseLoad = 2, // 有緩存就用緩存,沒有才發請求
NSURLRequestReturnCacheDataDontLoad = 3, // 離線模式,只用緩存,一律不請求
NSURLRequestReloadRevalidatingCacheData = 5, // 未實作
};
網路服務類型則影響系統對這條請求的排程優先級:
typedef NS_ENUM(NSUInteger, NSURLRequestNetworkServiceType) {
NSURLNetworkServiceTypeDefault = 0, // 一般網路流量
NSURLNetworkServiceTypeVoIP = 1, // VoIP 控制流量
NSURLNetworkServiceTypeVideo = 2, // 影片流量
NSURLNetworkServiceTypeBackground = 3, // 背景流量
NSURLNetworkServiceTypeVoice = 4 // 語音資料
};
NSURLRequest 建好之後,絕大多數屬性都是只讀的,這也是很多人卡住的地方。需要動態調整就用它的子類 NSMutableURLRequest:
@property (nullable, copy) NSURL *URL; @property NSURLRequestCachePolicy cachePolicy; @property NSTimeInterval timeoutInterval; @property (nullable, copy) NSURL *mainDocumentURL; @property NSURLRequestNetworkServiceType networkServiceType; @property BOOL allowsCellularAccess;
下面這些只有在 NSMutableURLRequest 上才能設置:
// 請求方法,預設 GET @property (copy) NSString *HTTPMethod; // 整體設置請求頭 @property (nullable, copy) NSDictionary<NSString *, NSString *> *allHTTPHeaderFields; // 單個設置 / 追加請求頭字段 - (void)setValue:(nullable NSString *)value forHTTPHeaderField:(NSString *)field; - (void)addValue:(NSString *)value forHTTPHeaderField:(NSString *)field; // POST 的請求體 @property (nullable, copy) NSData *HTTPBody; // 以流的形式提供請求體(適合大檔案) @property (nullable, retain) NSInputStream *HTTPBodyStream; // 是否自動附帶並處理 Cookie @property BOOL HTTPShouldHandleCookies; // 是否允許管線化,預設關閉;部分伺服器開啟後可提升效能 @property BOOL HTTPShouldUsePipelining;
實務提醒:HTTPBody 與 HTTPBodyStream 互斥,兩者只能選一個。另外 setting HTTPMethod 時要留意,把請求方法設成 POST 並不會自動幫你把參數編碼進 body,body 的組裝與 Content-Type 都得自己處理。
請求成功後,系統會先給你一個回執對象,再開始餵資料。通用屬性如下:
// 請求的 URL @property (nullable, readonly, copy) NSURL *URL; // 回應的 MIME 類型 @property (nullable, readonly, copy) NSString *MIMEType; // 內容長度 @property (readonly) long long expectedContentLength; // 文字編碼名稱 @property (nullable, readonly, copy) NSString *textEncodingName; // 建議檔名,預設以 URL 為名、MIME 類型為副檔名 @property (nullable, readonly, copy) NSString *suggestedFilename;
若是 HTTP 請求,實際拿到的會是它的子類 NSHTTPURLResponse,多出兩個常用屬性:
// 狀態碼 @property (readonly) NSInteger statusCode; // 全部回應頭 @property (readonly, copy) NSDictionary *allHeaderFields;
寫網路層時,把 statusCode 的判斷放在解析 body 之前,能省掉大量無效解析:先確認 2xx,再決定要不要往下走。至於 expectedContentLength 返回 -1 的情形(伺服器沒給 Content-Length),做進度條時要特別處理,不能當成 0 來算百分比。