Alibaba Cloud DNS：iOS SDK開發指南

概述

iOS SDK目前的版本封裝了移動解析HTTPDNS的DoH JSON API，提供介面函數給iOS APP進行網域名稱解析，並且提供了基於TTL和LRU策略的高效網域名稱緩衝功能。開發人員利用本SDK，可以在自己的iOS APP中輕鬆接入移動解析HTTPDNS，解決網域名稱解析異常的問題，低成本實現網域名稱解析精準調度。

iOS 14 開始系統原生支援兩種標準規範的 Encrypted DNS，分別是 DNS over TLS 與 DNS over HTTPS，您可以參考iOS14原生加密DNS方案瞭解如何設定移動解析HTTPDNS為加密DNS預設解析器。

SDK有如下優勢：

• 簡單易用：

  使用者僅需整合我們提供的SDK，便可接入移動解析HTTPDNS業務。接入方法簡單易用，為使用者提供更為輕鬆便捷的解析服務。

• 零延遲：

  SDK內部實現了LRU的緩衝機制，將每次網域名稱解析後的IP緩衝到本地；並且主動更新TTL到期緩衝，保證緩衝及時有效，從而協助使用者達到網域名稱解析零延遲的效果。

您可以參考alidns_ios_demo.樣本工程源碼瞭解如何使用本SDK。

SDK整合

引入SDK

SDK初始化

您需先在控制台註冊自己的應用，擷取應用的唯一標識和鑒權參數，SDK整合之後進行SDK初始化。

在application:didFinishLaunchingWithOptions:初始化SDK。

DNSResolver *resolver = [DNSResolver share];
//setAccountId:@"******"：星號內容填您在控制台“接入配置”頁面展示的 Account ID
//andAccessKeyId:@"********"：星號內容填您在控制台“接入配置”建立的密鑰的 AccessKey ID
//andAccesskeySecret:@"********"：星號內容填您在控制台“接入配置”建立的密鑰的 AccessKey Secret
[resolver setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];
//指定網域名稱自動更新到期緩衝，當前限制數組中最多包含10個網域名稱
[resolver setKeepAliveDomains:@[@"使用者指定網域名稱1",@"使用者指定網域名稱2"]];
//對後續可能要解析的網域名稱進行預先載入
[resolver preloadDomains:@[@"網域名稱1", @"網域名稱2", @"網域名稱3"] complete:^{
//所有網域名稱預先載入完成
}];

API介紹

常用設定

1、Account ID和鑒權

必傳參數，您在控制台註冊自己的應用後，控制台會為此應用產生唯一標識Account ID，鑒權功能來保障使用者身份安全，防止被第三方未授權者盜用。使用者請參考建立密鑰，在控制台建立AccessKey，並在APP中通過如下代碼設定：

//setAccountId:@"******"：星號內容填您在控制台“接入配置”頁面展示的 Account ID
//andAccessKeyId:@"********"：星號內容填您在控制台“接入配置”建立的密鑰的 AccessKey ID
//andAccesskeySecret:@"********"：星號內容填您在控制台“接入配置”建立的密鑰的 AccessKey Secret
[[DNSResolver share] setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];

2、解析通訊協定設定

SDK支援設定DNS解析請求協議類型，可自主選擇通過HTTP或HTTPS協議解析，具體可通過scheme屬性進行設定。

SDK預設並推薦使用HTTPS協議進行解析，因為HTTPS協議安全性更好。移動解析HTTPDNS的計費項目是按HTTP的解析次數進行收費，其中HTTPS是按5倍HTTP流量進行計費，開發人員可以根據自身實際業務需要選擇scheme類型。如下設定：

[DNSResolver share].scheme = DNSResolverSchemeHttps;

3、設定是否開啟緩衝

SDK可設定開啟緩衝功能，如果緩衝功能開啟，在第一次解析過網域名稱後，後續再解析時，優先擷取緩衝中的資料，這可大大提高解析速度。

SDK預設開啟緩衝。若要設定不開啟緩衝，則需要通過以下代碼設定：

[DNSResolver share].cacheEnable=NO;

4、設定網域名稱緩衝保持

SDK在緩衝功能已開啟的情況下，可設定針對某些網域名稱開啟緩衝保持功能，如果該功能開啟，SDK會自動更新這些網域名稱的到期緩衝，保障使用者快取資料及時更新，但是可能會帶來網域名稱解析次數和用戶端流量消耗的增多。如果不設定該功能，那麼SDK不會自動進行到期緩衝更新，只有當使用者調用解析方法時，才會再次進行緩衝更新。若要設定某些網域名稱的緩衝保持需要通過以下代碼設定：

//當前限制數組中最多包含10個網域名稱
[[DNSResolver share] setKeepAliveDomains:@[@"www.taobao.com",@"www.aliyun.com"]];

5、預解析

由於SDK可以設定開啟緩衝功能，在第一次解析完網域名稱產生緩衝後，後續再次解析此網域名稱時解析速度可提升至0時延。因此，建議在app啟動後，對app中可能要解析的網域名稱進行預解析。

程式碼範例：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   // Override point for customization after application launch.
   
   DNSResolver *resolver = [DNSResolver share];
   //setAccountId:@"******"：星號內容填您在控制台“接入配置”頁面展示的 Account ID
   //andAccessKeyId:@"********"：星號內容填您在控制台“接入配置”建立的密鑰的 AccessKey ID
   //andAccesskeySecret:@"********"：星號內容填您在控制台“接入配置”建立的密鑰的 AccessKey Secret
   [resolver setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];
   resolver.cacheEnable = YES;
   //對後續可能要解析的網域名稱進行預先載入
   [resolver preloadDomains:@[@"網域名稱1", @"網域名稱2", @"網域名稱3"] complete:^{
       //所有網域名稱預先載入完成
       
   }];
   
   return YES;
}

其它進階設定

1、設定是否使用服務端IPV6地址

移動解析HTTPDNS服務支援IPv4、IPv6雙棧訪問。SDK預設使用IPv4地址訪問DNS伺服器進行解析。

如果需要通過IPv6地址訪問DNS伺服器進行解析（當前網路需要支援IPv6），則需要通過以下代碼設定：

[DNSResolver share].ipv6Enable = YES;

2、short模式

移動解析HTTPDNS的DoH JSON API返回資料分為全量JSON和簡要IP數組格式。SDK預設為全量JSON格式。

若要設定為簡要IP數組格式，則需要通過以下代碼設定：

[DNSResolver share].shortEnable = YES;

3、設定緩衝數量

SDK若開啟了緩衝功能，可以自訂緩衝數量（支援範圍100～500之間）。

SDK預設的緩衝數量為100個網域名稱。若要自訂緩衝數量，可通過cacheCountLimit屬性進行設定：

[DNSResolver share].cacheCountLimit = 200;

4、設定是否開啟IP測速

SDK可設定開啟IP測速，如果IP測速開啟，解析結果會優先返回速度最快的解析結果IP地址，數組會按照測速結果由快到慢的順序排列。

SDK預設沒有開啟IP測速。若要設定開啟IP測速，則需要通過以下代碼設定：

[DNSResolver share].speedTestEnable=YES;

5、設定IP測速方式

SDK可設定IP測速的方式，如果IP測速開啟，並且設定該參數為0，則使用ICMP探測；如果設定該參數為80、443或其它支援的連接埠號碼，則為socket指定連接埠探測。

SDK預設該參數為0。若要設定socket指定連接埠探測，則需要通過以下代碼設定：

[DNSResolver share].speedPort = 80;

6、設定是否開啟依據ISP網路區分網域名稱緩衝

SDK可設定是否開啟依據ISP網路區分網域名稱緩衝。如果開啟，則在不同網路環境下網域名稱快取資料分別儲存互不影響。如果不開啟，則不同網路下使用同一份網域名稱快取資料。

SDK預設沒有開啟依據ISP網路區分網域名稱緩衝功能，若要開啟該功能，則需要通過以下代碼設定：

[DNSResolver share].ispEnable = YES;

7、設定否定緩衝最大TTL時間

SDK可設定否定緩衝（網域名稱沒有配置對應的IP地址，導致解析結果沒有IP返回的無效緩衝）的最大TTL時間，如果設定了該時間，則會限制否定緩衝的最大TTL不超過該設定時間。

SDK預設該參數為30s。若要設定否定緩衝最大TTL時間，則需要通過以下代碼設定：

[DNSResolver share].maxNegativeCache = 30;

8、設定緩衝最大TTL時間

SDK可設定緩衝的最大TTL時間，如果設定了該時間，則會限制緩衝的最大TTL不超過該設定時間。

SDK預設該參數為3600s。若要設定緩衝最大TTL時間，則需要通過以下代碼設定：

[DNSResolver share].maxCacheTTL= 3600;

9、設定是否開啟緩衝永不到期

[DNSResolver share].immutableCacheEnable = NO;// 預設不開啟緩衝永不到期

10、timeout

timeout屬性為網域名稱解析的逾時時間。預設逾時時間為3s，使用者可自訂逾時時間，建議設定在2~5s之間。

服務API

程式碼範例：

/// 預解析網域名稱資訊，可在程式啟動時調用，解析結果會存入緩衝，加快後續網域名稱解析速度
/// 自動感知網路環境（ipv4-only、ipv6-only、ipv4和ipv6雙棧）解析得到適用於當前網路環境的ip
/// @param domainArray  網域名稱數組
/// @param complete     解析完成後回調
- (void)preloadDomains:(NSArray<NSString *> *)domainArray complete:(void(^)(void))complete;

/// 擷取網域名稱解析後的ip數組，自動感知網路環境（ipv4-only、ipv6-only、ipv4和ipv6雙棧）得到適用於當前網路環境的ip，
/// 如果開啟了緩衝開關，那麼優先擷取緩衝中的資料返回，如果沒有緩衝或者緩衝到期，那麼會通過網路請求擷取對應的IP返回；如果沒有開啟緩衝開關，那麼直接通過網路請求擷取對應的IP返回。
/// @param domain           網域名稱
/// @param complete       回調(所有ip地址)
- (void)getIpsDataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

/// 自動感知網路環境（ipv4-only、ipv6-only、ipv4和ipv6雙棧）直接從緩衝中擷取適用於當前網路環境的ip數組，無需等待.  
/// 如無緩衝，則返回 nil；如果有緩衝並且enable設為YES，則會返回快取資料給使用者，若快取資料到期則非同步解析網域名稱更新快取資料；如果有緩衝並且enable設為NO，那麼當緩衝到期時會返回nil給使用者並非同步解析網域名稱更新快取資料。
/// @param domain   網域名稱
/// @param enable   是否允許返回到期ip
- (NSArray<NSString *> *)getIpsByCacheWithDomain:(NSString *)domain andExpiredIPEnabled:(BOOL)enable;

/// 擷取網域名稱解析後的IPv4資訊數組
/// 如果開啟了緩衝開關，那麼優先擷取緩衝中的資料返回，如果沒有緩衝或者緩衝到期，那麼會通過網路請求擷取對應的IP返回；如果沒有開啟緩衝開關，那麼直接通過網路請求擷取對應的IP返回。
/// @param domain           網域名稱
/// @param complete       回調(所有網域名稱資訊)
- (void)getIpv4InfoWithDomain:(NSString *)domain complete:(void(^)(NSArray<DNSDomainInfo *> *domainInfoArray))complete;

/// 擷取網域名稱解析後的IPv6資訊數組
/// 如果開啟了緩衝開關，那麼優先擷取緩衝中的資料返回，如果沒有緩衝或者緩衝到期，那麼會通過網路請求擷取對應的IP返回；如果沒有開啟緩衝開關，那麼直接通過網路請求擷取對應的IP返回。
/// @param domain           網域名稱
/// @param complete       回調(所有網域名稱資訊)
- (void)getIpv6InfoWithDomain:(NSString *)domain complete:(void(^)(NSArray<DNSDomainInfo *> *domainInfoArray))complete;

/// 擷取網域名稱解析後的IPv4資訊
/// 如果開啟了緩衝開關，那麼優先擷取緩衝中的資料返回，如果沒有緩衝或者緩衝到期，那麼會通過網路請求擷取對應的IP返回；如果沒有開啟緩衝開關，那麼直接通過網路請求擷取對應的IP返回。
/// @param domain           網域名稱
/// @param complete       回調(所有網域名稱資訊中隨機一個)
- (void)getRandomIpv4InfoWithDomain:(NSString *)domain complete:(void(^)(DNSDomainInfo *domainInfo))complete;

/// 擷取網域名稱解析後的IPv6資訊
/// 如果開啟了緩衝開關，那麼優先擷取緩衝中的資料返回，如果沒有緩衝或者緩衝到期，那麼會通過網路請求擷取對應的IP返回；如果沒有開啟緩衝開關，那麼直接通過網路請求擷取對應的IP返回。
/// @param domain           網域名稱
/// @param complete       回調(所有網域名稱資訊中隨機一個)
- (void)getRandomIpv6InfoWithDomain:(NSString *)domain complete:(void(^)(DNSDomainInfo *domainInfo))complete;

/// 擷取網域名稱解析後的IPv4地址數組
/// 如果開啟了緩衝開關，那麼優先擷取緩衝中的資料返回，如果沒有緩衝或者緩衝到期，那麼會通過網路請求擷取對應的IP返回；如果沒有開啟緩衝開關，那麼直接通過網路請求擷取對應的IP返回。
/// @param domain           網域名稱
/// @param complete       回調(所有ip地址)
- (void)getIpv4DataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

/// 擷取網域名稱解析後的IPv6地址數組
/// 如果開啟了緩衝開關，那麼優先擷取緩衝中的資料返回，如果沒有緩衝或者緩衝到期，那麼會通過網路請求擷取對應的IP返回；如果沒有開啟緩衝開關，那麼直接通過網路請求擷取對應的IP返回。
/// @param domain           網域名稱
/// @param complete       回調(所有ip地址)
- (void)getIpv6DataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

/// 擷取網域名稱解析後的IPv4地址
/// 如果開啟了緩衝開關，那麼優先擷取緩衝中的資料返回，如果沒有緩衝或者緩衝到期，那麼會通過網路請求擷取對應的IP返回；如果沒有開啟緩衝開關，那麼直接通過網路請求擷取對應的IP返回。
/// @param domain            網域名稱
/// @param complete        回調(所有ip地址中隨機一個)
- (void)getRandomIpv4DataWithDomain:(NSString *)domain complete:(void(^)(NSString *data))complete;

/// 擷取網域名稱解析後的IPv6地址
/// 如果開啟了緩衝開關，那麼優先擷取緩衝中的資料返回，如果沒有緩衝或者緩衝到期，那麼會通過網路請求擷取對應的IP返回；如果沒有開啟緩衝開關，那麼直接通過網路請求擷取對應的IP返回。
/// @param domain            網域名稱
/// @param complete        回調(所有ip地址中隨機一個)
- (void)getRandomIpv6DataWithDomain:(NSString *)domain complete:(void(^)(NSString *data))complete;

/// 預解析網域名稱IPv4資訊，可在程式啟動時調用，將解析結果存入緩衝，加快後續網域名稱解析速度
/// @param domainArray  網域名稱數組
/// @param complete         解析完成後回調
- (void)preloadIpv4Domains:(NSArray<NSString *> *)domainArray complete:(void(^)(void))complete;

/// 預解析網域名稱IPv6資訊，可在程式啟動時調用，將解析結果存入緩衝，加快後續網域名稱解析速度
/// @param domainArray  網域名稱數組
/// @param complete         解析完成後回調
- (void)preloadIpv6Domains:(NSArray<NSString *> *)domainArray complete:(void(^)(void))complete;

/// 直接從緩衝中擷取ipv4解析結果，無需等待.  
/// 如無緩衝，則返回 nil；如果有緩衝並且enable設為YES，則會返回快取資料給使用者，若快取資料到期則非同步解析網域名稱更新快取資料；如果有緩衝並且enable設為NO，那麼當緩衝到期時會返回nil給使用者並非同步解析網域名稱更新快取資料。
/// @param domain   網域名稱
/// @param enable   是否允許返回到期ip
- (NSArray<NSString *> *)getIpv4ByCacheWithDomain:(NSString *)domain andExpiredIPEnabled:(BOOL)enable;

/// 直接從緩衝中擷取ipv6解析結果，無需等待.  
/// 如無緩衝，則返回 nil；如果有緩衝並且enable設為YES，則會返回快取資料給使用者，若快取資料到期則非同步解析網域名稱更新快取資料；如果有緩衝並且enable設為NO，那麼當緩衝到期時會返回nil給使用者並非同步解析網域名稱更新快取資料。
/// @param domain   網域名稱
/// @param enable   是否允許返回到期ip
- (NSArray<NSString *> *)getIpv6ByCacheWithDomain:(NSString *)domain andExpiredIPEnabled:(BOOL)enable;

///統計資訊收集
-(NSArray *)getRequestReportInfo;

API使用樣本

1、設定基本資料

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   // Override point for customization after application launch.
   //唯一初始化方式
   DNSResolver *resolver = [DNSResolver share];
   //setAccountId:@"******"：星號內容填您在控制台“接入配置”頁面展示的 Account ID
   //andAccessKeyId:@"********"：星號內容填您在控制台“接入配置”建立的密鑰的 AccessKey ID
   //andAccesskeySecret:@"********"：星號內容填您在控制台“接入配置”建立的密鑰的 AccessKey Secret
   [resolver setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];
   //指定網域名稱自動更新到期緩衝，當前限制數組中最多包含10個網域名稱
	 [resolver setKeepAliveDomains:@[@"使用者指定網域名稱1",@"使用者指定網域名稱2"]];
   //對後續可能要解析的網域名稱進行預先載入，可提前擷取解析結果並存入緩衝
   [resolver preloadDomains:@[@"網域名稱1", @"網域名稱2", @"網域名稱3"] complete:^{
       //所有網域名稱預先載入完成
       
   }];
   return YES;
}

2、網域名稱解析介面

SDK提供了多種網域名稱解析方法供使用者選擇和使用，可在DNSResolver.h標頭檔中查看。 下面以其中一個自動區分網路環境（IPv4-only、IPv6-only、IPv4和IPv6雙棧）的解析方法為例，進行說明。

介面聲明：

/// 擷取網域名稱解析後的ip數組，自動區分網路環境（ipv4-only、ipv6-only、ipv4和ipv6雙棧）得到適用於當前網路環境的ip
/// 如果開啟了緩衝開關，那麼優先擷取緩衝中的資料返回，如果沒有緩衝或者緩衝到期，那麼會通過網路請求擷取對應的IP返回；如果沒有開啟緩衝開關，那麼直接通過網路請求擷取對應的IP返回。
/// @param domain           網域名稱
/// @param complete       回調(所有ip地址)
- (void)getIpsDataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

介面調用樣本：

[[DNSResolver share] getIpsDataWithDomain:@"www.taobao.com" complete:^(NSArray<NSString *> *dataArray) {
    //dataArray為網域名稱www.taobao.com所對應的IP地址數組
   if (dataArray.count > 0) {
       //TODO: 使用IP地址進行url串連
   }    
}];

3、直接從緩衝中擷取解析結果

介面聲明：

/// 自動區分網路環境（ipv4-only、ipv6-only、ipv4和ipv6雙棧）直接從緩衝中擷取適用於當前網路環境的ip數組，無需等待.  
/// 如無緩衝，則返回 nil；如果有緩衝並且enable設為YES，則會返回快取資料給使用者，若快取資料到期則非同步解析網域名稱更新快取資料；如果有緩衝並且enable設為NO，那麼當緩衝到期時會返回nil給使用者並非同步解析網域名稱更新快取資料。
/// @param domain   網域名稱
/// @param enable   是否允許返回到期ip
- (NSArray<NSString *> *)getIpsByCacheWithDomain:(NSString *)domain andExpiredIPEnabled:(BOOL)enable;

調用樣本：

NSArray *result = [[DNSResolver share] getIpsByCacheWithDomain:@"網域名稱" andExpiredIPEnabled:YES];
//拿到緩衝結果
if (result.count > 0) {
   //TODO: 使用ip地址進行url串連
   
}

注意：直接從緩衝中擷取緩衝結果，速度較快，但無緩衝、或者有緩衝但緩衝的解析結果已到期並且enable為NO時，返回結果會為nil。

4、刪除緩衝

介面聲明：

///hostArray為需要清除的host網域名稱數組。如果需要清空全部資料，傳nil或者空數組即可
-(void)clearHostCache:(NSArray <NSString *>*)hostArray;

調用樣本：

[[DNSResolver share] clearHostCache:@[@"網域名稱1", @"網域名稱2"]];

5、統計資訊收集

介面聲明：

///統計資訊收集
-(NSArray *)getRequestReportInfo;

調用樣本：

NSArray *array = [[DNSResolver share] getRequestReportInfo];

資料格式：

 (
      {
         avgRtt = "1";                                // 網域名稱平均解析時間ms
         cacheDnsNum = 0;                             // 命中緩衝次數                       
         domain = "www.taobao.com";                   // 解析的網域名稱
         gobackLocaldnsNum = 0;                       // 降級到LocalDNS的次數
         localErro = 0;                               // LocalDNS解析失敗次數
         maxRtt = "60";                               // 網域名稱最大解析時間ms
         noPermissionErro = 0;                        // 使用者鑒權失敗次數
         noResponseErro = 0;                          // 請求逾時無應答次數          
         requestPDnsNum = 1;                          // 遞迴查詢的次數
         sp = "中國移動";                                // 電訊廠商名字
         successNum = 1;                              // 解析成功次數
         timeoutErro = 0;                             // 網路逾時錯誤次數
         type = 28;                                   // ip類型1代表ipv4、28代表ipv6
         urlParameterErro = 0;                        // 請求參數格式錯誤次數
         urlPathErro = 0;                             // URL錯誤次數
      }
         ......
 );

注意事項

1. pdns-sdk-ios.framework支援最低版本為iOS9.0。

2. 使用HTTP協議請求時，需要在Info.plist中設定App Transport Security Settings->Allow Arbitrary Loads為YES。

3. 通過移動解析HTTPDNS獲得網域名稱的IP地址後，用戶端可以使用這個IP發送業務請求，HTTP要求標頭的Host欄位需改為原來的網域名稱。

   例如：

   //ip為原網域名稱解析後的ip地址
   NSURL *url = [NSURL URLWithString:[NSString stringWithFormat:@"https://%@", ip]];
   NSMutableURLRequest *mutableReq = [NSMutableURLRequest requestWithURL:url cachePolicy:NSURLRequestUseProtocolCachePolicy timeoutInterval: 10];
   //設定host
   [mutableReq setValue:@"原網域名稱" forHTTPHeaderField:@"host"];

4. 為了保證使用者業務正常，當通過SDK沒有擷取到網域名稱的IP時，需要開發人員使用原網域名稱的地址進行請求來作為兜底，範例程式碼如下：

   NSArray *array = [[DNSResolver share] getIpsByCacheWithDomain:@"原網域名稱" andExpiredIPEnabled:YES];
   NSString *ip = array.firstObject;
   if (ip.length > 0) {
       //替換url中的host為ip進行介面請求
       
   }else{
       //添加兜底處理(使用原url進行介面請求)
   }

5. 當存在中間HTTP代理時，用戶端發起的請求中請求行會使用絕對路徑的URL，在您開啟移動解析HTTPDNS並採用IP URL進行訪問時，中間代理將識別您的IP資訊並將其作為真實訪問的HOST資訊傳遞給目標伺服器，這時目標伺服器將無法處理這類無真實HOST資訊的HTTP請求。我們建議您檢測當前裝置是否開啟了網路代理程式，然後在代理模式下不使用移動解析HTTPDNS進行網域名稱解析。

常見問題

SDK/API相關FAQ