前陣子替公司重構了網路層,原本打算完成後就整理成文章,接著忙新版本需求,一直拖到現在才有時間落筆。
舊的網路層是直接拖入 AFNetworking 原始碼,並大量修改其中的實作。兩年過去,AF 已經迭代多次,整個遷移成本高得驚人。不過翻閱前輩留下的程式碼,能看出許多思路與我一致,只是落地方式不同,對我反而是很好的參照。
這次架構也參考了 Casa 的分層思想,但細節上做了自己的調整。本文不談太多理論與術語,一方面是方便閱讀,另一方面架構設計的核心始終是思路——思路清楚了,實作自然水到渠成。
1. 網路接口規範
2. 多伺服器多環境設定
3. 網路層資料傳遞(請求與回傳)
4. 業務層對接方式
5. 請求的自動取消
6. 錯誤處理機制
專案已開源,有興趣可直接參考:
https://github.com/SummertimSadness/NetWorkingDemo
規範的重要性常被低估。一套合理的約定能省下大量程式碼,特別是接口的向前相容。Demo 中的請求範例是網路上找的,並不符合我這套規範,僅供參考。
接口首次回傳為字典,結構固定為 code、msg、data 三部分:
"code": 0,
"msg": "",
"data": {
"upload_log": true,
"has_update": false,
"admin_id": "529ecfd64"
}
code:錯誤碼。可自訂一套編碼規則,例如 200 表示正常、1 表示需要重新登入,方便快速定位問題。
msg:可直接顯示給使用者的文案。這意味著錯誤提示不能是一串英文錯誤字串。
data:真正的業務資料,可以是字典也可以是陣列。
接口已經定義好 code 與 msg,是否就不需要錯誤處理了?當然不是。伺服端的錯誤邏輯相對單純,data 內部的資料仍可能異常,錯誤處理不可省略,後文會單獨說明。
這一點多數團隊都能做到,但仍有例外。我們有個早期接口就不合規:channelID、device_id 這類通用資訊以字串拼接在 URL 後方,真正的業務參數卻要轉成 JSON 塞進單一欄位,形成 GET 與 POST 並存的混合形式,網路層被迫寫特殊分支處理。可見標準化的請求方式有多重要。
Null 在 iOS 中是個特殊的存在,我的建議是放在客戶端處理,理由有幾點:
1. 規範往往不是一開始就能定好的,老接口要移除 Null 欄位改動極大;
2. 客戶端過濾一次即可一勞永逸,不必日後因接口異動而崩潰,搭配 Model 相關第三方庫也能很好地解決;
3. Swift 的型別檢查非常嚴格,規範寫得清楚,根本不可能出現參數型別導致的崩潰。
這部分基本沿用 Casa 的設計,我額外延伸了多環境的處理。小專案通常只有一台伺服器,但電商類專案顯然不可能,多伺服器是常態。實作上以列舉變數搭配 ServerFactory 單例,取得對應的伺服器設定。
標準的 App 有四套環境:開發、測試、預發、正式。伺服器端程式碼的更新必須依序流轉,而不是全部在正式環境改。開發分支永遠保持最新狀態,測試階段的修改要合併回開發分支,預發階段的變動幅度更小,正式環境則處理線上緊急缺陷,修完同樣併回開發分支。此外還可能衍生 hotfix 環境、H5 或後台的本地除錯環境。
客戶端同樣存在這些環境,並且必須提供切換入口。
Demo 中設計了兩套機制:一套是首次安裝時的初始化環境(透過巨集定義),另一套是手動切換(列舉 EnvironmentType)。這裡有個容易繞暈的優先序:巨集定義的正式環境優先於手動切換,而手動切換優先於巨集定義的其他環境。
// 巨集環境設定
#if !defined YA_BUILD_FOR_DEVELOP
// 手動環境切換設定
#ifdef YA_BUILD_FOR_RELEASE
// 優先使用巨集定義的正式環境
self.environmentType = EnvironmentTypeRelease;
#else
// 手動切換後會把設定存入偏好
NSNumber *type = [[NSUserDefaults standardUserDefaults] objectForKey:@"environmentType"];
if (type) {
// 優先讀取手動切換設定
self.environmentType = (EnvironmentType)[type integerValue];
} else {
#ifdef YA_BUILD_FOR_DEVELOP
self.environmentType = EnvironmentTypeDevelop;
#elif defined YA_BUILD_FOR_TEST
self.environmentType = EnvironmentTypeTest;
#elif defined YA_BUILD_FOR_PRERELEASE
self.environmentType = EnvironmentTypePreRelease;
#elif defined YA_BUILD_FOR_HOTFIX
self.environmentType = EnvironmentTypeHotFix;
#endif
}
#endif
結果是:當巨集定義為正式環境時,手動切換會失效,這正是給一般使用者的發行版本所需;而其他巨集環境下則仍可切換到正式環境。
這裡有個小小的不一致:手動切換自訂環境的實作放在基底類別中,其他環境的位址設定卻寫在協定裡。可以這樣理解——基底類別提供既定回傳值,協定則負責回傳值的彈性;既然自訂環境不需要額外彈性,放在基底類別更合適。思路決定方向,實作可以變通,若堅持放進協定也未嘗不可,只是要重複貼上幾段完全相同的程式碼,而這正是我最不想看到的情況。
Model 層負責提供高擴充性,可針對不同伺服器追加設定,例如加密方式、資料解析方式。前面提過,統一規範往往無法一次到位,相容性需求此時就會浮現,各伺服器的個性化設定於是在協定中宣告並實作,基底類別只管回傳值。

Client、BaseEngine/DataEngine、RequestDataModel 三者之間的資料流。
在我的理解中,一次網路請求可拆成兩步:整理資料,以及產生 Request 並送出。基於這個思路,我拆出了 Client 與 Engine,再把 URLRequestGenerator 從 Client 中獨立出來,Engine 則往下拆成 BaseEngine 與面向不同業務的 DataEngine。而資料要在 BaseEngine、Client、URLRequestGenerator 之間流動,於是有了 RequestDataModel。
@interface YAAPIBaseRequestDataModel : NSObject
/** 網路請求參數 */
@property (nonatomic, strong) NSString *apiMethodPath; // 請求位址
@property (nonatomic, assign) YAServiceType serviceType; // 伺服器標識
@property (nonatomic, strong) NSDictionary *parameters; // 請求參數
@property (nonatomic, assign) YAAPIManagerRequestType requestType; // 請求方式
@property (nonatomic, copy) CompletionDataBlock responseBlock; // 回調
// 上傳相關
@property (nonatomic, strong) NSString *dataFilePath;
@property (nonatomic, strong) NSString *dataName;
@property (nonatomic, strong) NSString *fileName;
@property (nonatomic, strong) NSString *mimeType;
// 進度回調
@property (nonatomic, copy) ProgressBlock uploadProgressBlock;
@property (nonatomic, copy) ProgressBlock downloadProgressBlock;
@end
這些屬性涵蓋了請求發起與回傳所需的全部資訊,帶來的效益相當可觀。相信不少人遇過這樣的場景:因為參數不同而寫了一堆方法對外暴露,最後呼叫的其實是同一個實作;方法一多,連自己都搞不清楚該調哪一個。我確實踩過這個坑,所以現在的呼叫方式收斂成一行:
// 沒有回調、沒有冗餘參數,只有一個 dataModel
[[YAAPIClient sharedInstance] callRequestWithRequestModel:dataModel];
產生 NSURLRequest 也是一行:
NSURLRequest *request = [[YAAPIURLRequestGenerator sharedInstance] generateWithRequestDataModel:requestModel];
YAAPIClient 與 YAAPIURLRequestGenerator 的方法數都極少,程式碼各約 120 行,就完成了請求的發起與落地,可讀性非常高。
另一個好處是高擴充性。過去網路層要增刪一個參數,往往連帶得改方法名與方法體,多個呼叫端也要一起改;改用 RequestDataModel 之後,只需增刪屬性並調整方法體即可。這兩個工作量的差距非常明顯。
Client 負責兩件事:產生 NSURLRequest,以及據此建立 NSURLSessionDataTask 並送出,同時對 Engine 暴露取消操作。URLRequestGenerator 則負責解析 dataModel,輸出對應伺服器的 Request。兩者皆為單例。
-(void)callRequestWithRequestModel:(YAAPIBaseRequestDataModel *)requestModel {
NSURLRequest *request = [[YAAPIURLRequestGenerator sharedInstance] generateWithRequestDataModel:requestModel];
AFURLSessionManager *sessionManager = self.sessionManager;
NSURLSessionDataTask *task = [sessionManager
dataTaskWithRequest:request
uploadProgress:requestModel.uploadProgressBlock
downloadProgress:requestModel.downloadProgressBlock
completionHandler:^(NSURLResponse *response, id responseObject, NSError *error) {
// 請求落地
}];
[task resume];
}
取消機制沿用 Casa 的思路,以 requestID 綁定 task,此處不再贅述。
Engine(或說 APIManager)在我的設計中既不完全離散,也不完全集約。
Casa 的兩種模型是這樣的:集約型只有一個類別接收 API 名稱、參數與回調點,再統一起飛:
[APIRequest startRequestWithApiName:@"itemList.v1" params:params success:@selector(success:) fail:@selector(fail:) target:self];
離散型則是一個 API 對應一個 Manager,API 名稱與回調方式都封裝在 Manager 內:
[self.itemListAPIManager loadDataWithParams:params];
由此延伸出幾個問題:以字典傳遞參數對網路層而言是黑箱,業務層還得自行關注接口欄位變化;離散型會造成 Manager 數量爆炸;集約型則讓取消操作變得棘手;而取消並非每個接口都必要,若做成部分離散部分集約,整體結構會相當凌亂。
我的設計針對上述痛點:
1. DataEngine 只接收必要參數,不使用字典。
@interface SearchDataEngine : NSObject
+ (YABaseDataEngine *)control:(NSObject *)control searchKey:(NSString *)searchKey complete:(CompletionDataBlock)responseBlock;
@end
control 參數留給自動取消機制,後文再談;searchKey 則是搜尋關鍵字。呼叫端因此變得非常直觀:
self.searchDataEngine = [SearchDataEngine control:self searchKey:@"關鍵字" complete:^(id data, NSError *error) {
if (error) {
NSLog(@"%@", error.localizedDescription);
} else {
NSLog(@"%@", data);
}
}];
2. 以業務維度切分 DataEngine。例如 BBSDataEngine、ShopDataEngine、UserInforDataEngine,各自封裝本業務的所有接口。我們的專案有三百多個接口,拆分後約十幾個 DataEngine,規模可控;若採用離散型設計,畫面會非常壯觀。
下一篇再繼續談自動取消與錯誤處理的實作細節。