Java SDK接入指南 - HTTPDNS

通過用戶端接入概述您已經瞭解了 HTTPDNS 接入的基本原理，本文介紹通過 Java SDK 接入 HTTPDNS 的方法。

重要

若為 Android 應用，請優先參考Android SDK接入手冊接入。Java SDK 不支援本地持久化緩衝和網路變化自動解析等 Android 特有功能。

一、快速入門

1.1 開通服務

請參考快速入門開通HTTPDNS。

1.2 擷取配置

請參考開發配置在EMAS控制台開發配置中擷取AccountId/SecretKey/AESSecretKey等資訊，用於初始化SDK。

二、安裝配置

根據您的專案構建工具，選擇 Gradle 或 Maven 其中一種方式配置即可。

2.1 配置倉庫地址

SDK 發布在阿里雲 Maven 倉庫，需要先添加倉庫地址。

Gradle

在 settings.gradle 或 build.gradle 中添加：

repositories {
    maven { 
      url 'https://maven.aliyun.com/nexus/content/repositories/releases/' 
    }
}

Maven

在 pom.xml 中添加：

<repositories>
    <repository>
        <id>aliyun</id>
        <url>https://maven.aliyun.com/nexus/content/repositories/releases/</url>
    </repository>
</repositories>

2.2 添加 SDK 依賴

Gradle

在 build.gradle 的 dependencies 中添加：

dependencies {
    implementation 'com.aliyun.ams:alicloud-java-httpdns:1.0.0'
}

Maven

在 pom.xml 的 <dependencies> 中添加：

<dependency>
    <groupId>com.aliyun.ams</groupId>
    <artifactId>alicloud-java-httpdns</artifactId>
    <version>1.0.0</version>
</dependency>

三、配置和使用

3.1 初始化配置

應用啟動後，需要先初始化 SDK，才能調用 HTTPDNS 能力。初始化主要是配置 AccountId/SecretKey 等資訊及功能開關。範例程式碼如下：

import com.alibaba.sdk.java.httpdns.HttpDnsClient;
import com.alibaba.sdk.java.httpdns.InitConfig;
import com.alibaba.sdk.java.httpdns.RequestIpType;

// 建立配置
InitConfig config = new InitConfig.Builder()
    .setSecretKey("your-secret-key")           // 加簽密鑰
    .setEnableHttps(true)                      // 使用 HTTPS 解析
    .setTimeoutMillis(2000)                    // 逾時時間（毫秒）
    .setEnableExpiredIp(true)                  // 允許使用到期 IP
    .enableMemoryCache(true)                   // 啟用記憶體緩衝（預設 true）
    .build();

// 初始化
HttpDnsClient.init("your-account-id", config);

// 擷取用戶端執行個體
HttpDnsClient client = HttpDnsClient.getClient("your-account-id");

重要

setEnableHttps參數設定為true後，計費會增加，請仔細閱讀產品計費文檔。
如果您對網域名稱資訊或SDNS參數有更高的安全訴求，可以配置setAesSecretKey參數啟用對解析請求進行內容層加密，使用內容加密後計費會增加，請仔細閱讀產品計費文檔。

3.1.1 日誌配置

應用開發過程中，如果要輸出 HTTPDNS 的日誌，可以通過 HttpDnsLog 配置：

import com.alibaba.sdk.java.httpdns.log.HttpDnsLog;
import com.alibaba.sdk.java.httpdns.ILogger;

// 開啟日誌輸出
HttpDnsLog.enable(true);

// 設定自訂日誌介面
HttpDnsLog.setLogger(new ILogger() {
    @Override
    public void log(String msg) {
        System.out.println("[HTTPDNS] " + msg);
    }
});

3.1.2 SessionId 記錄

應用在運行過程中，可以擷取 sessionId 記錄到資料擷取系統中，用於線上問題排查：

String sessionId = client.getSessionId();
System.out.println("SessionId = " + sessionId);

3.2 網域名稱解析

3.2.1 預解析

完成HTTPDNS初始化後，可以對後續可能用到的熱點網域名稱配置預解析，以便SDK提前解析，減少後續網域名稱解析時請求的時延，範例程式碼如下：

List<String> hosts = Arrays.asList("www.aliyun.com", "www.example.com");
client.setPreResolveHosts(hosts, RequestIpType.both);

3.2.2 網域名稱解析

當需要解析網域名稱時，可以通過調用網域名稱解析方法解析網域名稱擷取IP，範例程式碼如下：

HTTPDNSResult result = client.getHttpDnsResultForHostSyncNonBlocking(
    "www.aliyun.com", 
    RequestIpType.both
);

if (result != null && result.getIps() != null) {
    String[] ipv4List = result.getIps();
}

if (result != null && result.getIpv6s() != null) {
    String[] ipv6List = result.getIpv6s();
}

四、後續步驟

擷取到 IP 後，需要將其應用到實際的網路請求中，根據實際使用的網路程式庫，可以參考Java端HTTPDNS+OkHttp最佳實務、Java端HTTPDNS+Apache HttpClient最佳實務。

如果要對SDK進行更精細的配置或者使用鑒權請求等其它功能，可以參考Java SDK API。

五、注意事項

升級SDK後編譯失敗
如果您升級SDK版本後，出現編譯失敗的情況，有可能是因為SDK的API有調整，請查看Java SDK API使用替換的新介面。
務必編寫降級代碼
降級代碼指的是當HTTPDNS無法擷取期望結果時，需要降級使用Local DNS去完成網域名稱解析。
記錄從HTTPDNS擷取的IP及sessionId
我們提供了用於解析問題排查的解決方案，需要您將從HTTPDNS擷取的IP及sessionId記錄到日誌中，詳情請參見如何使用“會話追蹤方案”排查解析異常。