NSError 是 Cocoa 框架中用來封裝錯誤資訊的核心類別。它提供兩種初始化方式,其中 domain 不可為空,dict 則可以為空:
- (instancetype)initWithDomain:(NSErrorDomain)domain code:(NSInteger)code userInfo:(nullable NSDictionary *)dict; + (instancetype)errorWithDomain:(NSErrorDomain)domain code:(NSInteger)code userInfo:(nullable NSDictionary *)dict;
NSError 有幾個重要的唯讀屬性:domain(錯誤域)、code(錯誤代碼)、userInfo(錯誤資訊字典),以及一系列本地化相關屬性,例如 localizedDescription(本地化描述)、localizedFailureReason(失敗原因)、localizedRecoverySuggestion(恢復建議)、localizedRecoveryOptions(恢復選項)等。
錯誤域主要有四個:Carbon 框架的 Error 歸於 NSOSStatusErrorDomain,POSIX error 歸於 NSPOSIXErrorDomain,Mach 錯誤歸於 NSMachErrorDomain,而我們日常 iOS 開發最常使用的是 NSCocoaErrorDomain。NSError.h 中定義了這四個預設域:
FOUNDATION_EXPORT NSErrorDomain const NSCocoaErrorDomain; FOUNDATION_EXPORT NSErrorDomain const NSPOSIXErrorDomain; FOUNDATION_EXPORT NSErrorDomain const NSOSStatusErrorDomain; FOUNDATION_EXPORT NSErrorDomain const NSMachErrorDomain;
此外,userInfo 字典有幾個預定義的鍵名值得記住:NSUnderlyingErrorKey(底層錯誤,通用鍵)、NSLocalizedDescriptionKey(詳細描述)、NSLocalizedFailureReasonErrorKey(失敗原因)、NSLocalizedRecoverySuggestionErrorKey(恢復建議)、NSLocalizedRecoveryOptionsErrorKey(恢復選項),以及其他如 NSFilePathErrorKey、NSURLErrorKey、NSStringEncodingErrorKey 等。
用法示例如下:
NSDictionary *userInfo1 = [NSDictionary dictionaryWithObjectsAndKeys:@"由於文件不存在,無法打開", NSLocalizedDescriptionKey, @"失敗原因:文件不存在", NSLocalizedFailureReasonErrorKey, @"恢復建議:請創建該文件", NSLocalizedRecoverySuggestionErrorKey, nil]; NSError *error = [[NSError alloc] initWithDomain:NSCocoaErrorDomain code:4 userInfo:userInfo1]; NSLog(@"========%@", [error localizedDescription]); NSLog(@"========%@", [error localizedFailureReason]); NSLog(@"========%@", [error localizedRecoverySuggestion]);
這裡的 code 設為 4,對照下方對照表可知代表「文件不存在」。若 userInfo 傳入自訂字典,可看到自訂的本地化輸出;若傳入 nil,則會顯示系統的預設本地化描述。
以下是 Cocoa 錯誤域(NSCocoaErrorDomain)中常見的錯誤碼:
NSFileNoSuchFileError = 4, NSFileLockingError = 255, NSFileReadUnknownError = 256, NSFileReadNoPermissionError = 257, NSFileReadInvalidFileNameError = 258, NSFileReadCorruptFileError = 259, NSFileReadNoSuchFileError = 260, NSFileReadInapplicableStringEncodingError = 261, NSFileReadUnsupportedSchemeError = 262, NSFileReadTooLargeError = 263, NSFileReadUnknownStringEncodingError = 264, NSFileWriteUnknownError = 512, NSFileWriteNoPermissionError = 513, NSFileWriteInvalidFileNameError = 514, NSFileWriteOutOfSpaceError = 640, NSFileWriteVolumeReadOnlyError = 642, NSKeyValueValidationError = 1024, NSFormattingError = 2048, NSUserCancelledError = 3072,
而在網路相關的開發中,最常遇到的是 NSURLErrorDomain 下的錯誤碼:
NSURLErrorUnknown = -1, NSURLErrorCancelled = -999, NSURLErrorBadURL = -1000, NSURLErrorTimedOut = -1001, NSURLErrorUnsupportedURL = -1002, NSURLErrorCannotFindHost = -1003, NSURLErrorCannotConnectToHost = -1004, NSURLErrorNetworkConnectionLost = -1005, NSURLErrorDNSLookupFailed = -1006, NSURLErrorHTTPTooManyRedirects = -1007, NSURLErrorResourceUnavailable = -1008, NSURLErrorNotConnectedToInternet = -1009, NSURLErrorSecureConnectionFailed = -1200, NSURLErrorServerCertificateUntrusted = -1202, NSURLErrorCannotLoadFromNetwork = -2000, NSURLErrorCannotCreateFile = -3000, NSURLErrorCannotOpenFile = -3001, NSURLErrorCannotWriteToFile = -3003,
其中 -1009(未連網)、-1001(逾時)、-1003(找不到主機)是網路請求除錯時最常見的幾個錯誤,值得優先熟悉。
系統的 NSError 完全是可以自訂的。以下示範如何封裝一個錯誤管理類,把錯誤碼翻譯成易讀的字串,並在需要時生成對應的 NSError 物件。
首先是 YXError.h:
#import// 自行定義錯誤碼列舉 typedef enum : NSUInteger { Crash = -10000, DisConnect, Unknow, } YXErrorCode; @interface YXError : NSObject + (NSError *)errorCode:(YXErrorCode)code userInfo:(NSDictionary *)dic; + (NSString *)transformCodeToStringInfo:(YXErrorCode)code; @end
接著是 YXError.m,透過一個靜態字典維護錯誤碼與描述文字的對應關係:
#import "YXError.h"
static NSDictionary *errorDictionary = nil;
@implementation YXError
+ (void)initialize {
if (self == [YXError class]) {
errorDictionary = @{
@(Crash) : @"Crash",
@(DisConnect) : @"DisConnect",
@(Unknow) : @"Unknow",
};
}
}
+ (NSError *)errorCode:(YXErrorCode)code userInfo:(NSDictionary *)dic {
return [NSError errorWithDomain:errorDictionary[@(code)] code:code userInfo:dic];
}
+ (NSString *)transformCodeToStringInfo:(YXErrorCode)code {
return errorDictionary[@(code)];
}
@end
使用時非常直覺,既能生成錯誤物件,也能把錯誤碼翻譯成字串:
#import "YXError.h" // 定制一個 NSError NSError *error = [YXError errorCode:Crash userInfo:nil]; NSLog(@"%@", error); // 將 code 值翻譯成字串 NSLog(@"%@", [YXError transformCodeToStringInfo:-10000]);
透過這種做法,你能把散落在專案各處的錯誤碼集中管理,讓錯誤處理變得清晰且易於維護,這正是自訂 NSError 的價值所在。