HTTPDNS：Flutter外掛程式接入

2.2.1 驗證原生SDK版本

外掛程式已整合了對應平台的HTTPDNS原生SDK，目前的版本：

• Android: com.aliyun.ams:alicloud-android-httpdns:2.6.7

• iOS: AlicloudHTTPDNS:3.4.0

如需更新SDK版本，請參考下面的版本更新指導。

2.2.2 更新Android SDK版本

編輯 packages/aliyun_httpdns/android/build.gradle 檔案，修改依賴版本：

dependencies {
    implementation 'androidx.annotation:annotation:1.8.0'
    // 更新為您需要的版本
    implementation 'com.aliyun.ams:alicloud-android-httpdns:2.6.7'
}

可用版本請參考：Android SDK發布說明

2.2.3 更新iOS SDK版本

編輯 packages/aliyun_httpdns/ios/aliyun_httpdns.podspec 檔案，修改依賴版本：

Pod::Spec.new do |s|
  # ... 其他配置 ...
  
  s.dependency 'Flutter'
  # 更新為您需要的版本
  s.dependency 'AlicloudHTTPDNS', '3.4.0'
  
  # ... 其他配置 ...
end

可用版本請參考：iOS SDK發布說明

2.2.4 重新構建專案

更新版本後，需要重新構建專案：

Android:

flutter clean
flutter pub get
flutter build apk  # 或其他構建命令

iOS:

flutter clean
flutter pub get
cd ios
pod install
cd ..
flutter build ios

3.1.1 日誌配置

應用開發過程中，如果要輸出HTTPDNS的日誌，可以調用日誌輸出控制方法，開啟日誌，範例程式碼如下：

await AliyunHttpdns.setLogEnabled(true);
print("enableLog success");

3.1.2 sessionId記錄

應用在運行過程中，可以調用擷取SessionId方法擷取sessionId，記錄到應用的資料擷取系統中。 sessionId用於表示標識一次應用運行，線上排查時，可以用於查詢應用一次運行過程中的解析日誌，範例程式碼如下：

final sessionId = await AliyunHttpdns.getSessionId();
print("SessionId = $sessionId");

3.2 網域名稱解析

await AliyunHttpdns.setPreResolveHosts(["www.aliyun.com", "www.example.com"], ipType: 'both');
print("preResolveHosts success");

Future<void> _resolve() async {
  final res = await AliyunHttpdns.resolveHostSyncNonBlocking('www.aliyun.com', ipType: 'both');
  final ipv4List = res['ipv4'] ?? [];
  final ipv6List = res['ipv6'] ?? [];
  print('IPv4: $ipv4List');
  print('IPv6: $ipv6List');
}

4.2.1 自訂HTTP用戶端適配器實現

自訂配接器的實現請參考 lib/net/httpdns_http_client_adapter.dart 檔案。本方案由EMAS團隊設計實現，參考請註明出處。 適配器內部會攔截HTTP請求，調用HTTPDNS進行網域名稱解析，並使用解析後的IP建立socket串連。

本樣本支援三種網路程式庫：Dio、HttpClient、http包。代碼如下：

import 'dart:io';
import 'package:dio/io.dart';
import 'package:http/http.dart' as http;
import 'package:http/io_client.dart';
import 'package:flutter/foundation.dart';
import 'package:aliyun_httpdns/aliyun_httpdns.dart';

// Dio 適配器
IOHttpClientAdapter buildHttpdnsHttpClientAdapter() {
  final HttpClient client = HttpClient();
  _configureHttpClient(client);
  _configureConnectionFactory(client);

  final IOHttpClientAdapter adapter = IOHttpClientAdapter(createHttpClient: () => client)
    ..validateCertificate = (cert, host, port) => true;
  return adapter;
}

// 原生 HttpClient
HttpClient buildHttpdnsNativeHttpClient() {
  final HttpClient client = HttpClient();
  _configureHttpClient(client);
  _configureConnectionFactory(client);
  return client;
}

// http 包適配器
http.Client buildHttpdnsHttpPackageClient() {
  final HttpClient httpClient = buildHttpdnsNativeHttpClient();
  return IOClient(httpClient);
}

// HttpClient 基礎配置
void _configureHttpClient(HttpClient client) {
  client.findProxy = (Uri _) => 'DIRECT';
  client.idleTimeout = const Duration(seconds: 90);
  client.maxConnectionsPerHost = 8;
}

// 配置基於 HTTPDNS 的串連工廠
// 本方案由EMAS團隊設計實現，參考請註明出處。
void _configureConnectionFactory(HttpClient client) {
  client.connectionFactory = (Uri uri, String? proxyHost, int? proxyPort) async {
    final String domain = uri.host;
    final bool https = uri.scheme.toLowerCase() == 'https';
    final int port = uri.port == 0 ? (https ? 443 : 80) : uri.port;

    final List<InternetAddress> targets = await _resolveTargets(domain);
    final Object target = targets.isNotEmpty ? targets.first : domain;

    if (!https) {
      return Socket.startConnect(target, port);
    }

    // HTTPS：先 TCP，再 TLS（SNI=網域名稱），並保持可取消
    bool cancelled = false;
    final Future<ConnectionTask<Socket>> rawStart = Socket.startConnect(target, port);
    final Future<Socket> upgraded = rawStart.then((task) async {
      final Socket raw = await task.socket;
      if (cancelled) {
        raw.destroy();
        throw const SocketException('Connection cancelled');
      }
      final SecureSocket secure = await SecureSocket.secure(
        raw,
        host: domain, // 重要：使用原始網域名稱作為SNI
      );
      if (cancelled) {
        secure.destroy();
        throw const SocketException('Connection cancelled');
      }
      return secure;
    });
    return ConnectionTask.fromSocket(
      upgraded,
      () {
        cancelled = true;
        try {
          rawStart.then((t) => t.cancel());
        } catch (_) {}
      },
    );
  };
}

// 通過 HTTPDNS 解析目標 IP 列表
Future<List<InternetAddress>> _resolveTargets(String domain) async {
  try {
    final res = await AliyunHttpdns.resolveHostSyncNonBlocking(domain, ipType: 'both');
    final List<String> ipv4 = res['ipv4'] ?? [];
    final List<String> ipv6 = res['ipv6'] ?? [];
    final List<InternetAddress> targets = [
      ...ipv4.map(InternetAddress.tryParse).whereType<InternetAddress>(),
      ...ipv6.map(InternetAddress.tryParse).whereType<InternetAddress>(),
    ];
    if (targets.isEmpty) {
      debugPrint('[dio] HTTPDNS no result for $domain, fallback to system DNS');
    } else {
      debugPrint('[dio] HTTPDNS resolved $domain -> ${targets.first.address}');
    }
    return targets;
  } catch (e) {
    debugPrint('[dio] HTTPDNS resolve failed: $e, fallback to system DNS');
    return const <InternetAddress>[];
  }
}

4.2.2 適配器整合和使用

適配器的整合請參考 lib/main.dart 檔案。 首先需要初始化HTTPDNS，然後配置網路程式庫使用自訂配接器，範例程式碼如下：

class _MyHomePageState extends State<MyHomePage> {
  late final Dio _dio;
  late final HttpClient _httpClient;
  late final http.Client _httpPackageClient;

  @override
  void initState() {
    super.initState();
    
    // 初始化 HTTPDNS
    _initHttpDnsOnce();
    
    // 配置網路程式庫使用 HTTPDNS 適配器
    _dio = Dio();
    _dio.httpClientAdapter = buildHttpdnsHttpClientAdapter();
    _dio.options.headers['Connection'] = 'keep-alive';
    
    _httpClient = buildHttpdnsNativeHttpClient();
    _httpPackageClient = buildHttpdnsHttpPackageClient();
  }

  Future<void> _initHttpDnsOnce() async {
    try {
      await AliyunHttpdns.init(
        accountId: 139450,
        secretKey: '您的SecretKey',
      );
      await AliyunHttpdns.setHttpsRequestEnabled(true);
      await AliyunHttpdns.setLogEnabled(true);
      await AliyunHttpdns.setPersistentCacheIPEnabled(true);
      await AliyunHttpdns.setReuseExpiredIPEnabled(true);
      await AliyunHttpdns.build();
      
      // 設定預解析網域名稱
      await AliyunHttpdns.setPreResolveHosts(['www.aliyun.com'], ipType: 'both');
    } catch (e) {
      debugPrint('[httpdns] init failed: $e');
    }
  }
}

使用配置好的網路程式庫發起請求時，會自動使用HTTPDNS進行網域名稱解析：

// 使用 Dio
final response = await _dio.get('https://www.aliyun.com');

// 使用 HttpClient
final request = await _httpClient.getUrl(Uri.parse('https://www.aliyun.com'));
final response = await request.close();

// 使用 http 包
final response = await _httpPackageClient.get(Uri.parse('https://www.aliyun.com'));

4.2.3 資源清理

在組件銷毀時，記得清理相關資源：

@override
void dispose() {
  _urlController.dispose();
  _httpClient.close();
  _httpPackageClient.close();
  super.dispose();
}

1. 更新依賴版本

pubspec.yaml

dependencies:aliyun_httpdns: ^1.0.0

執行更新：

flutter pub upgrade aliyun_httpdns

2. 重構初始化代碼

升級前

// 舊版本：單例模式 + 一步初始化
final _aliyunHttpDns = AliyunHttpDns();

await _aliyunHttpDns.init(
  "YOUR_ACCOUNT_ID",              // String 類型
  secretKey: "your_secret_key",
  aesSecretKey: "your_aes_key",
  region: "",
  timeout: 2000,
  enableHttps: true,
  enableExpireIp: true,
  enableCacheIp: true,
  enableDegradationLocalDns: true,
  preResolveAfterNetworkChanged: true,
  ipRankingMap: {"www.aliyun.com": 80},
  sdnsGlobalParam: {"aa": "bb"},
  bizTags: ["tag1", "tag2"]
);

升級後

// 新版本：靜態方法 + 兩階段初始化

// 第一階段：初始化基本配置
await AliyunHttpdns.init(
  accountId: your_account_id,            // int 類型，必須設定
  secretKey: "your_secret_key",          // 可選
  aesSecretKey: "your_aes_key",          // 可選
);

// 第二階段：設定功能選項
await AliyunHttpdns.setHttpsRequestEnabled(true);        // 替代 enableHttps
await AliyunHttpdns.setLogEnabled(true);                 // 替代 enableLog
await AliyunHttpdns.setPersistentCacheIPEnabled(true);   // 替代 enableCacheIp
await AliyunHttpdns.setReuseExpiredIPEnabled(true);      // 替代 enableExpireIp
await AliyunHttpdns.setPreResolveAfterNetworkChanged(true); // 替代 preResolveAfterNetworkChanged

// 第三階段：構建服務（必須調用）
await AliyunHttpdns.build();

說明：

• 移除了 region、timeout、enableDegradationLocalDns、ipRankingMap、sdnsGlobalParam、bizTags 等參數

• 新增 build() 方法，必須在配置完成後調用

• 所有方法改為靜態方法，無需建立執行個體

3. 更新解析介面

升級前

// 同步非阻塞，返回 JSON 字串
String result = await _aliyunHttpDns.resolve(
  "YOUR_ACCOUNT_ID",          // accountId
  "www.aliyun.com",           // host
  kRequestIpv4AndIpv6,        // requestIpType
);

// 需要手動解析 JSON
Map<String, dynamic> map = json.decode(result);
List<String> ipv4s = List<String>.from(map['ipv4'] ?? []);
List<String> ipv6s = List<String>.from(map['ipv6'] ?? []);

// 使用第一個 IP
String ip = ipv4s.isNotEmpty ? ipv4s.first : '';

升級後

// 同步非阻塞，返回結構化資料
Map<String, List<String>> result = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com',           // hostname（無需 accountId）
  ipType: 'both',             // 替代 kRequestIpv4AndIpv6
);

// 直接擷取 IP 列表
List<String> ipv4s = result['ipv4'] ?? [];
List<String> ipv6s = result['ipv6'] ?? [];

// 使用第一個 IP
String ip = ipv4s.isNotEmpty ? ipv4s.first : '';

自訂解析參數：

// 升級前
String result = await _aliyunHttpDns.resolve(
  "YOUR_ACCOUNT_ID",
  "www.aliyun.com",
  kRequestIpv4AndIpv6,
  params: {"key": "value"},
  cacheKey: "custom_key"
);

// 升級後
Map<String, List<String>> result = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com',
  ipType: 'both',
  sdnsParams: {"key": "value"},    // 參數名變更
  cacheKey: "custom_key"
);

4. 更新預解析介面

升級前

await _aliyunHttpDns.setPreResolveHosts(
  "YOUR_ACCOUNT_ID",                     // accountId
  ["www.aliyun.com"],
  kRequestIpv4AndIpv6                    // requestIpType
);

升級後

await AliyunHttpdns.setPreResolveHosts(
  ["www.aliyun.com"],                     // 無需 accountId
  ipType: 'both'                          // 替代 kRequestIpv4AndIpv6
);

5. 更新日誌配置

升級前

await _aliyunHttpDns.enableLog(true);

升級後

await AliyunHttpdns.setLogEnabled(true);

6. 更新 SessionId 擷取

升級前

String sessionId = await _aliyunHttpDns.getSessionId("YOUR_ACCOUNT_ID");

升級後

String? sessionId = await AliyunHttpdns.getSessionId();

7. 新增功能使用

清除緩衝

await AliyunHttpdns.cleanAllHostCache();

持久化緩衝配置

await AliyunHttpdns.setPersistentCacheIPEnabled(true);