HTTPDNS:Integrasikan Flutter SDK

3.1.1. Konfigurasi log

Untuk mengeluarkan log HTTPDNS selama pengembangan aplikasi, Anda dapat memanggil metode kontrol output log untuk mengaktifkan logging. Kode berikut memberikan contoh:

AliyunHttpdns.setLogEnabled(true);

// Penangan log kustom (opsional)
AliyunHttpdns.setLogHandler((message) {
  print(message);
});

3.1.2. Pencatatan SessionId

Saat aplikasi berjalan, Anda dapat memanggil metode untuk mengambil sessionId dan mencatatnya dalam sistem pengumpulan data aplikasi Anda. SessionId mengidentifikasi satu kali proses aplikasi dan dapat digunakan untuk mengkueri log resolusi untuk proses tertentu selama troubleshooting online. Kode berikut memberikan contoh:

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

3.2. Resolusi nama domain

await AliyunHttpdns.setPreResolveHosts(["www.aliyun.com", "www.example.com"], ipType: HttpdnsIpType.auto);

Future<void> _resolve() async {
  final result = await AliyunHttpdns.resolveHostSyncNonBlocking('www.aliyun.com', ipType: HttpdnsIpType.auto);
  final ipv4List = result?.ips ?? [];
  final ipv6List = result?.ipv6s ?? [];
  print('IPv4: $ipv4List');
  print('IPv6: $ipv6List');
}

4.2.1. Implementasi adapter klien HTTP kustom

Untuk implementasi adapter kustom, lihat file lib/net/httpdns_http_client_adapter.dart. Solusi ini dirancang dan diimplementasikan oleh tim EMAS. Jika Anda merujuk solusi ini, harap cantumkan atribusi. Adapter ini mengintersepsi permintaan HTTP, memanggil HTTPDNS untuk resolusi nama domain, dan menggunakan alamat IP yang telah diresolusi untuk membuat koneksi socket.

Contoh ini mendukung tiga library jaringan: Dio, HttpClient, dan paket http. Kodenya sebagai berikut:

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';

// Adapter 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 native
HttpClient buildHttpdnsNativeHttpClient() {
  final HttpClient client = HttpClient();
  _configureHttpClient(client);
  _configureConnectionFactory(client);
  return client;
}

// Adapter paket http
http.Client buildHttpdnsHttpPackageClient() {
  final HttpClient httpClient = buildHttpdnsNativeHttpClient();
  return IOClient(httpClient);
}

// Konfigurasi dasar HttpClient
void _configureHttpClient(HttpClient client) {
  client.findProxy = (Uri _) => 'DIRECT';
  client.idleTimeout = const Duration(seconds: 30);
  client.maxConnectionsPerHost = 8;
}

// Konfigurasikan connection factory berdasarkan HTTPDNS
// Solusi ini dirancang dan diimplementasikan oleh tim EMAS. Cantumkan atribusi jika Anda merujuknya.
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: Pertama TCP, lalu TLS (SNI=nama domain), dan tetap bisa dibatalkan
    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, // Penting: Gunakan nama domain asli sebagai 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 (_) {}
      },
    );
  };
}

// Resolusi daftar IP target melalui HTTPDNS
Future<List<InternetAddress>> _resolveTargets(String domain) async {
  try {
    final result = await AliyunHttpdns.resolveHostSyncNonBlocking(domain, ipType: HttpdnsIpType.auto);
    final List<String> ipv4 = result?.ips ?? [];
    final List<String> ipv6 = result?.ipv6s ?? [];
    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. Integrasi dan penggunaan adapter

Untuk integrasi adapter, lihat file lib/main.dart. Pertama, inisialisasi HTTPDNS. Kemudian, konfigurasikan library jaringan untuk menggunakan adapter kustom. Kode berikut memberikan contoh:

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

  @override
  void initState() {
    super.initState();
    
    // Inisialisasi HTTPDNS
    _initHttpDnsOnce();
    
    // Konfigurasikan library jaringan untuk menggunakan adapter HTTPDNS
    _dio = Dio();
    _dio.httpClientAdapter = buildHttpdnsHttpClientAdapter();
    _dio.options.headers['Connection'] = 'keep-alive';
    
    _httpClient = buildHttpdnsNativeHttpClient();
    _httpPackageClient = buildHttpdnsHttpPackageClient();
  }

  Future<void> _initHttpDnsOnce() async {
    try {
      final config = AliyunHttpdnsConfig(
        accountId: Your AccountId,
        secretKey: 'Your SecretKey',
        httpsEnabled: true,
        reuseExpiredIPEnabled: true,
      );
      await AliyunHttpdns.init(config);
      AliyunHttpdns.setLogEnabled(true);
      
      // Tetapkan host untuk pre-resolve
      await AliyunHttpdns.setPreResolveHosts(['www.aliyun.com'], ipType: HttpdnsIpType.auto);
    } catch (e) {
      debugPrint('[httpdns] init failed: $e');
    }
  }
}

Saat Anda menggunakan library jaringan yang telah dikonfigurasi untuk membuat permintaan, library tersebut secara otomatis menggunakan HTTPDNS untuk resolusi nama domain:

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

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

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

4.2.3. Bersihkan resource

Saat komponen dihapus, Anda harus membersihkan resource terkait:

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

5.3.1 Resolusi sinkron non-blocking (direkomendasikan)

Segera mengembalikan hasil cache. Jika cache tidak ditemukan, mengembalikan null dan memulai permintaan di latar belakang.

final result = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com', 
  ipType: HttpdnsIpType.auto,
);

// Dengan parameter SDNS
final result2 = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
  sdnsParams: {'key': 'value'},
  cacheKey: 'custom_cache_key',
);

5.3.2 Resolusi sinkron blocking

Menunggu hingga hasil diperoleh atau permintaan timeout.

final result = await AliyunHttpdns.resolveHostSync(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
);

// Dengan parameter SDNS
final result2 = await AliyunHttpdns.resolveHostSync(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
  sdnsParams: {'key': 'value'},
  cacheKey: 'custom_cache_key',
);

5.3.3 Resolusi callback asinkron

Mengembalikan hasil resolusi melalui fungsi callback.

await AliyunHttpdns.resolveHostAsync(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
  callback: (result) {
    print('Hasil resolusi: $result');
  },
);

// Dengan parameter SDNS
await AliyunHttpdns.resolveHostAsync(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
  sdnsParams: {'key': 'value'},
  cacheKey: 'custom_cache_key',
  callback: (result) {
    print('Hasil resolusi: $result');
  },
);

Deskripsi parameter

Struktur data yang dikembalikan (ResolveResult)

Langkah-langkah peningkatan detail

dependencies:aliyun_httpdns: ^2.0.0

flutter pub upgrade aliyun_httpdns

// 1.x: Inisialisasi dua tahap
await AliyunHttpdns.init(
  accountId: Your AccountId,
  secretKey: "your_secret_key",
  aesSecretKey: "your_aes_key",
);

await AliyunHttpdns.setHttpsRequestEnabled(true);
await AliyunHttpdns.setPersistentCacheIPEnabled(true);
await AliyunHttpdns.setReuseExpiredIPEnabled(true);
await AliyunHttpdns.setPreResolveAfterNetworkChanged(true);
await AliyunHttpdns.setIPRankingList({'www.aliyun.com': 443});

await AliyunHttpdns.build();

final config = AliyunHttpdnsConfig(
  accountId: Your AccountId,
  secretKey: 'your_secret_key',
  aesSecretKey: 'your_aes_key',
  httpsEnabled: true,
  persistentCacheEnabled: true,
  reuseExpiredIPEnabled: true,
  preResolveAfterNetworkChanged: true,
  ipRankingDatasource: {'www.aliyun.com': 443},
);
await AliyunHttpdns.init(config);

final res = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com',
  ipType: 'both',
);
final ipv4s = res['ipv4'] ?? [];
final ipv6s = res['ipv6'] ?? [];

final result = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
);
final ipv4s = result?.ips ?? [];
final ipv6s = result?.ipv6s ?? [];

await AliyunHttpdns.setPreResolveHosts(['www.aliyun.com']);

await AliyunHttpdns.setPreResolveHosts(['www.aliyun.com']);

AliyunHttpdns.setLogHandler((message) {
  print(message);
});

await AliyunHttpdns.cleanAllHostCache();

// Bersihkan semua cache
await AliyunHttpdns.cleanHostCache(null);

// Bersihkan cache untuk nama domain tertentu (baru)
await AliyunHttpdns.cleanHostCache(['www.aliyun.com']);

Tabel pemetaan peningkatan API (1.x → 2.0)

Langkah-langkah peningkatan detail

dependencies:aliyun_httpdns: ^1.0.0

flutter pub upgrade aliyun_httpdns

// Versi lama: Pola singleton + inisialisasi satu tahap
final _aliyunHttpDns = AliyunHttpDns();

await _aliyunHttpDns.init(
  "YOUR_ACCOUNT_ID",              // Tipe 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"]
);

// Versi baru: Metode statis + inisialisasi dua tahap

// Tahap 1: Inisialisasi konfigurasi dasar
await AliyunHttpdns.init(
  accountId: your_account_id,            // tipe int, wajib
  secretKey: "your_secret_key",          // Opsional
  aesSecretKey: "your_aes_key",          // Opsional
);

// Tahap 2: Atur opsi fitur
await AliyunHttpdns.setHttpsRequestEnabled(true);        // Menggantikan enableHttps
await AliyunHttpdns.setLogEnabled(true);                 // Menggantikan enableLog
await AliyunHttpdns.setPersistentCacheIPEnabled(true);   // Menggantikan enableCacheIp
await AliyunHttpdns.setReuseExpiredIPEnabled(true);      // Menggantikan enableExpireIp
await AliyunHttpdns.setPreResolveAfterNetworkChanged(true); // Menggantikan preResolveAfterNetworkChanged

// Tahap 3: Bangun layanan (harus dipanggil)
await AliyunHttpdns.build();

// Sinkron non-blocking, mengembalikan string JSON
String result = await _aliyunHttpDns.resolve(
  "YOUR_ACCOUNT_ID",          // accountId
  "www.aliyun.com",           // host
  kRequestIpv4AndIpv6,        // requestIpType
);

// Memerlukan parsing JSON manual
Map<String, dynamic> map = json.decode(result);
List<String> ipv4s = List<String>.from(map['ipv4'] ?? []);
List<String> ipv6s = List<String>.from(map['ipv6'] ?? []);

// Gunakan IP pertama
String ip = ipv4s.isNotEmpty ? ipv4s.first : '';

// Sinkron non-blocking, mengembalikan data terstruktur
Map<String, List<String>> result = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com',           // hostname (accountId tidak diperlukan)
  ipType: 'both',             // Menggantikan kRequestIpv4AndIpv6
);

// Dapatkan daftar IP secara langsung
List<String> ipv4s = result['ipv4'] ?? [];
List<String> ipv6s = result['ipv6'] ?? [];

// Gunakan IP pertama
String ip = ipv4s.isNotEmpty ? ipv4s.first : '';

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

// Setelah peningkatan
Map<String, List<String>> result = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com',
  ipType: 'both',
  sdnsParams: {"key": "value"},    // Nama parameter diubah
  cacheKey: "custom_key"
);

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

await AliyunHttpdns.setPreResolveHosts(
  ["www.aliyun.com"],                     // accountId tidak diperlukan
  ipType: 'both'                          // Menggantikan kRequestIpv4AndIpv6
);

await _aliyunHttpDns.enableLog(true);

await AliyunHttpdns.setLogEnabled(true);

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

String? sessionId = await AliyunHttpdns.getSessionId();

await AliyunHttpdns.cleanAllHostCache();

await AliyunHttpdns.setPersistentCacheIPEnabled(true);

Tabel pemetaan peningkatan API