Flutter SDK接入

3.1.1 日志配置

应用开发过程中，如果要输出HTTPDNS的日志，可以调用日志输出控制方法，开启日志，示例代码如下：

AliyunHttpdns.setLogEnabled(true);

// 自定义日志处理器（可选）
AliyunHttpdns.setLogHandler((message) {
  print(message);
});

3.1.2 sessionId记录

应用在运行过程中，可以调用获取SessionId方法获取sessionId，记录到应用的数据采集系统中。 sessionId用于表示标识一次应用运行，线上排查时，可以用于查询应用一次运行过程中的解析日志，示例代码如下：

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

3.2 域名解析

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 自定义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: 30);
  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 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 适配器集成和使用

适配器的集成请参考 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 {
      final config = AliyunHttpdnsConfig(
        accountId: 您的AccountId,
        secretKey: '您的SecretKey',
        httpsEnabled: true,
        reuseExpiredIPEnabled: true,
      );
      await AliyunHttpdns.init(config);
      AliyunHttpdns.setLogEnabled(true);
      
      // 设置预解析域名
      await AliyunHttpdns.setPreResolveHosts(['www.aliyun.com'], ipType: HttpdnsIpType.auto);
    } 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();
}

5.3.1 同步非阻塞解析（推荐）

立即返回缓存结果，缓存未命中时返回空并在后台发起请求。

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

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

5.3.2 同步阻塞解析

阻塞等待直到获取结果或超时。

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

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

5.3.3 异步回调解析

通过回调函数返回解析结果。

await AliyunHttpdns.resolveHostAsync(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
  callback: (result) {
    print('解析结果: $result');
  },
);

// 带 SDNS 参数
await AliyunHttpdns.resolveHostAsync(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
  sdnsParams: {'key': 'value'},
  cacheKey: 'custom_cache_key',
  callback: (result) {
    print('解析结果: $result');
  },
);

解析参数说明

返回数据结构 (ResolveResult)

升级步骤详解

dependencies:aliyun_httpdns: ^2.0.0

flutter pub upgrade aliyun_httpdns

// 1.x：两阶段初始化
await AliyunHttpdns.init(
  accountId: 您的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: 您的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();

// 清除所有缓存
await AliyunHttpdns.cleanHostCache(null);

// 清除指定域名缓存（新增）
await AliyunHttpdns.cleanHostCache(['www.aliyun.com']);

API 升级映射表（1.x → 2.0）

升级步骤详解

dependencies:aliyun_httpdns: ^1.0.0

flutter pub upgrade aliyun_httpdns

// 旧版本：单例模式 + 一步初始化
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();

// 同步非阻塞，返回 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"
);

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

await AliyunHttpdns.setPreResolveHosts(
  ["www.aliyun.com"],                     // 无需 accountId
  ipType: 'both'                          // 替代 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);

API 升级映射表