waf-platform/HttpDNSSDK/docs/HTTPDNS SDK 集成文档（Flutter）.md

HTTPDNS SDK 集成文档（Flutter）

一、 准备工作

1. 获取参数：从控制台获取您的 AppId 和 apiUrl。
2. 环境要求：Flutter 2.15+ / Dart 2.15+。
3. 原生环境：
   • iOS 12.0+
   • Android API Level 21+

---

二、 安装配置

1. 引用本地插件

将插件源码 new_httpdns 放置在您的项目目录中（例如 packages/ 目录下），然后在 pubspec.yaml 中引用：

dependencies:
  new_httpdns:
    path: ./packages/new_httpdns

2. Android 配置（必须）

在 Android 项目的 android/settings.gradle.kts 中，添加插件内嵌的本地 Maven 仓库：

dependencyResolutionManagement {
    repositories {
        maven { url = uri("../packages/new_httpdns/android/libs/repo") }  // 路径与插件实际位置对应
        google()
        mavenCentral()
        // ...
    }
}

路径为相对于 android/ 目录的路径，请根据 new_httpdns 插件的实际放置位置调整。

3. 执行更新

在终端运行：

flutter pub get

---

三、 快速入门

1. 初始化 SDK

在 main() 函数中完成初始化工作。初始化分两步：先调用 init() 配置参数，再调用 build() 启动 SDK。

import 'package:new_httpdns/new_httpdns.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 第一步：配置参数
  await TrustAPPHttpdns.init(
    appId: "your-app-id",
    apiUrl: "https://your-api-url:8445", // 请包含协议与端口
    secretKey: "your-sign-secret",       // 如果开启了安全签名
  );

  // 第二步：可选配置项
  await TrustAPPHttpdns.setHttpsRequestEnabled(true);
  await TrustAPPHttpdns.setLogEnabled(false);           // 生产环境建议关闭
  await TrustAPPHttpdns.setPersistentCacheIPEnabled(true);
  await TrustAPPHttpdns.setReuseExpiredIPEnabled(true);

  // 第三步：启动 SDK（必须调用，否则 SDK 不会生效）
  await TrustAPPHttpdns.build();

  // 可选：预解析核心域名，加快首次请求速度
  await TrustAPPHttpdns.setPreResolveHosts(["www.example.com"], ipType: 'both');

  runApp(MyApp());
}

2. 域名解析

// 同步非阻塞获取缓存（推荐）
var result = await TrustAPPHttpdns.resolveHostSyncNonBlocking("www.example.com");
List<String> ipv4s = result['ipv4'];

---

四、 最佳实践：自动化业务请求

在 Flutter 中，证书校验通常较为复杂。我们为此专门开辟了 HttpAdapter 方案。

使用内置 Adapter

通过 createHttpAdapter 创建的实例，会自动处理域名解析、IP 直连及手动校验证书逻辑。

final adapter = TrustAPPHttpdns.createHttpAdapter();

try {
  final res = await adapter.request(
    Uri.parse("https://api.example.com/data"),
    method: 'GET',
    headers: {'Custom-Header': 'val'},
  );
  print("响应码: ${res.statusCode}");
  print("实际使用的 IP: ${res.usedIp}");
} catch (e) {
  print("请求失败: $e");
}

---

五、 核心原理

SNI 隐私与证书验证

Flutter 的 HttpClient 默认会发送 SNI。当我们为了防劫持而使用 IP 直连时，服务器可能因为解析不出 SNI 域名而拒绝握手。

插件解决之道：

1. Adapter 自动化：插件内部会解析目标域名，并在连接 IP 成功后，通过 Dart 的底层 HttpClient 注入原始域名作为 Host 头，确保服务端正常响应。
2. 证书校验：默认情况下，TrustAPPHttpdnsHttpAdapter 会信任所有证书（适用于 IP 直连场景）。如需严格证书验证，请勿在生产环境启用 allowInsecureCertificatesForDebugOnly，该选项仅供调试使用。

final adapter = TrustAPPHttpdns.createHttpAdapter(
  options: TrustAPPHttpdnsAdapterOptions(
    allowInsecureCertificatesForDebugOnly: false, // 生产环境保持 false
  ),
);

---

六、 API 全集参考

接口名	功能说明
init	核心。配置 AppId、apiUrl、secretKey 等参数，必须最先调用。
build	核心。完成所有配置后调用，正式启动 SDK，缺少此步 SDK 不生效。
setHttpsRequestEnabled	开启/关闭 HTTPS 请求（建议生产环境开启）。需在 build() 前调用。
setLogEnabled	开发者调试日志开关，生产环境建议关闭。需在 build() 前调用。
setPersistentCacheIPEnabled	开启/关闭 IP 磁盘持久化缓存。需在 build() 前调用。
setReuseExpiredIPEnabled	开启/关闭过期 IP 复用（网络差时兜底）。需在 build() 前调用。
setPreResolveHosts	预解析域名列表，加快首次业务请求速度。在 build() 后调用。
resolveHostSyncNonBlocking	立即从本地缓存读取 IP。若缓存未命中则触发后台更新，本次返回空。
createHttpAdapter	生成业务请求工具类，自动完成域名解析 + IP 直连 + Host 注入。
setPreResolveAfterNetworkChanged	网络切换后是否自动重新预解析。
setIPRankingList	设置 IP 优选列表，按延迟排序优先使用低延迟 IP。
getSessionId	获取当前 SDK 会话 ID，用于日志追踪。
cleanAllHostCache	清除所有域名的本地缓存。

---

七、 常见问题 (FAQ)

Q: 插件是否全平台通用？ A: 目前该插件仅针对 iOS 和 Android。在 Web 或 Desktop 端运行会抛出 unimplemented 错误，建议结合 kIsWeb 等进行环境判断。

Q: 如何处理解析超时？ A: TrustAPPHttpdnsAdapterOptions 中可配置 connectTimeoutMs。默认 3000ms。

Q: 如果 API 地址是 HTTP 的怎么办？ A: 强烈建议生产环境使用 HTTPS。如果测试环境必须用 HTTP，请在两端的原生配置文件（Info.plist / AndroidManifest.xml）中开启明文传输权限。