HarmonyOS端HTTPDNS+阿里雲OSS SDK最佳實務 - HTTPDNS

本文檔介紹在HarmonyOS用戶端上使用阿里雲OSS SDK接入HTTPDNS的方案。

1. 背景說明

阿里雲Object Storage Service（Object Storage Service）是一款通用的雲端儲存體服務，可讓開發人員在各類應用中便捷地儲存和訪問帳戶圖片、圖片、音視頻等檔案。在HarmonyOS端，可以通過整合OSS HarmonyOS SDK來完成。

為了提升檔案傳輸的穩定性和速度，可以將HTTPDNS SDK與OSS HarmonyOS SDK進行結合，對OSS網域名稱進行解析。這可以有效實現網域名稱防劫持和DNS解析加速，從而最佳化應用訪問OSS的網路體驗。

2. 接入步驟

在HarmonyOS上，將HTTPDNS與OSS SDK進行整合，整個接入過程分為以下兩個核心步驟：

建立一個整合了HTTPDNS解析能力的rcp.Session。
使用這個定製化的會話來初始化OSS用戶端。

2.1 建立整合HTTPDNS的Session

首先，需要建立一個rcp.Session執行個體，並在其配置中嵌入自訂的DNS解析規則，該規則會調用HTTPDNS服務來解析網域名稱。

HTTPDNS的完整接入流程，參考HarmonyOS SDK接入。

import { httpdns } from '@aliyun/httpdns';
import { rcp } from '@kit.RemoteCommunicationKit';

/**
 * 建立一個整合了阿里雲HTTPDNS解析能力的網路會話 (rcp.Session)。
 *
 * @param httpdnsAccountId 您的阿里雲HTTPDNS Account ID。
 * @returns 返回一個配置好DNS解析規則的 rcp.Session 執行個體。
 */
async function createHttpDnsEnhancedSession(httpdnsAccountId: string): Promise<rcp.Session> {
  const httpdnsService = await httpdns.getService(httpdnsAccountId);

  const sessionConfig: rcp.SessionConfiguration = {
    requestConfiguration: {
      dns: {
        dnsRules: (host: string): string[] => {
          try {
            const result = httpdnsService.getHttpDnsResultSyncNonBlocking(host);
            let addresses: string[] = [];

            if (result.ipv4s && result.ipv4s.length > 0) {
              addresses.push(...result.ipv4s);
            }
            
            if (result.ipv6s && result.ipv6s.length > 0) {
              addresses.push(...result.ipv6s);
            }

            if (addresses.length > 0) {
              return addresses; // 返回合并後的IP地址清單
            }
          } catch (error) {
            console.error(`[HttpDNS] 解析失敗: ${host}`, error);
          }
          
          // 當解析失敗或無結果時，返回空數組以降級到系統預設DNS
          return [];
        }
      }
    }
  };

  return rcp.createSession(sessionConfig);
}

2.2 使用該Session初始化OSS用戶端

其次，將上一步建立的rcp.Session執行個體，在初始化OSS用戶端時作為配置參數傳入。這樣，所有通過該用戶端發起的網路請求都將自動使用我們定義的HTTPDNS解析邏輯。

OSS SDK的接入和使用，可以參考OSS Harmony SDK（預覽版）。

import Client from '@aliyun/oss';
// 省略 createHttpDnsEnhancedSession 函數內容

/**
 * 示範如何初始化一個使用HTTPDNS增強會話的OSS用戶端。
 */
async function initializeOssClientWithHttpDns() {
  const YOUR_HTTPDNS_ACCOUNT_ID = 'your_httpdns_account_id'; // 替換為您的Account ID
  const YOUR_ACCESS_KEY_ID = 'your_access_key_id';         // 替換為您的AK
  const YOUR_ACCESS_KEY_SECRET = 'your_access_key_secret'; // 替換為您的SK
  const YOUR_REGION = 'oss-cn-hangzhou';                   // 替換為您的Region

  // 調用步驟一的函數，建立整合了HTTPDNS的Session
  const httpDnsSession = await createHttpDnsEnhancedSession(YOUR_HTTPDNS_ACCOUNT_ID);

  // 初始化OSS用戶端，並將建立好的Session執行個體傳遞進去
  const ossClient = new Client({
    accessKeyId: YOUR_ACCESS_KEY_ID,
    accessKeySecret: YOUR_ACCESS_KEY_SECRET,
    region: YOUR_REGION,
    session: httpDnsSession, // 核心：傳入定製化的session
  });

  console.log('OSS Client with HttpDNS initialized successfully!');

  // 此 ossClient 執行個體已成功整合HTTPDNS。
  // 後續操作（如上傳、下載）的網路請求將自動通過HTTPDNS解析。
  // await ossClient.putObject(...);
  
  return ossClient;
}

重要

HTTPDNS SDK初始化設定需要在OSS SDK初始化設定之前完成。

3. 總結

通過為OSS用戶端提供一個帶有自訂DNS解析規則的rcp.Session執行個體，可以在HarmonyOS上實現HTTPDNS與OSS SDK的結合，從而最佳化網路效能與安全性。

整合過程中的關鍵注意點如下：

初始化順序：必須先初始化HTTPDNS服務，再初始化OSS用戶端。
降級處理：dnsRules回調中，當HTTPDNS解析無結果或失敗時，務必返回空數組[]以啟用系統DNS降級。