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

Flutter SDK 集成文档（Edge HTTPDNS）

1. 版本与依赖

• SDK 插件：HttpDNSSDK/sdk/flutter/new_httpdns
• 环境要求：Flutter 2.15+ / Dart 2.15+

在 pubspec.yaml 中引用本地插件：

dependencies:
  new_httpdns:
    path: path/to/sdk/flutter/new_httpdns

执行 flutter pub get 完成安装。

2. SNI 行为说明（关键）

1. /resolve 请求链路（SDK -> 你的 HTTPDNS 服务域名）

• 走标准 HTTPS，默认携带 SNI（用于路由到边缘控制节点）。

2. 业务请求链路（拿到 CDN IP 后发起业务 HTTPS）

• IP 直连 + No-SNI：使用 TrustAPPHttpdnsHttpAdapter 进行请求。
• 逻辑：解析域名 -> 拿到 IP 列表 -> uri.replace(host: ip) -> req.headers.host = uri.host -> 清空 SNI。
• 仅支持 HTTPS URL。

3. 初始化 SDK（推荐用 TrustAPP 封装）

Dart

import 'package:new_httpdns/new_httpdns.dart';

bool ok = await TrustAPPHttpdns.init(
    appId: "your-app-id",
    primaryServiceHost: "httpdns.example.com",
    backupServiceHost: "httpdns-backup.example.com",
    servicePort: 443,
    secretKey: "your-sign-secret" // 可选，开启签名校验需传入
);

if (ok) {
    print("Edge HTTPDNS 初始化成功");
}

4. 解析域名获取 CDN IP

Dart

// V1 风格解析接口
Map<String, dynamic> result = await TrustAPPHttpdns.resolveHost(
    "api.example.com",
    qtype: 'A', // 可选 'A' 或 'AAAA'
    cip: '1.2.3.4' // 可选，模拟客户端 IP
);

List<String> ipv4s = result['ipv4'];
int ttl = result['ttl'];

5. 业务请求接入方式

使用 TrustAPPHttpdnsHttpAdapter 实现“SNI 隐匿”业务请求。

Dart

final adapter = TrustAPPHttpdns.createHttpAdapter(
    options: const TrustAPPHttpdnsAdapterOptions(
        connectTimeoutMs: 3000,
        readTimeoutMs: 5000,
        ipType: 'auto', // auto/ipv4/ipv6
    )
);

try {
    final res = await adapter.request(
        Uri.parse("https://api.example.com/path?x=1"),
        method: 'GET',
        headers: {'Custom-Header': 'Value'},
        body: null
    );

    print("Status Code: ${res.statusCode}");
    print("Body Length: ${res.body.length}");
    print("Used IP: ${res.usedIp}");
} catch (e) {
    print("请求失败: $e");
}

6. 其他常用接口

// 1. 设置预解析域名
await TrustAPPHttpdns.setPreResolveHosts(["api.example.com", "img.example.com"]);

// 2. 只有开启缓存时可用
Map<String, List<String>> cacheRes = await TrustAPPHttpdns.resolveHostSyncNonBlocking("api.example.com");

// 3. 开启持久化缓存（重启 App 后任然可用）
await TrustAPPHttpdns.setPersistentCacheIPEnabled(true);

// 4. 控制台日志（建议仅调试开启）
await TrustAPPHttpdns.setLogEnabled(true);

7. 验证建议

1. 验证 /resolve

• 观察控制台日志或抓包工具，解析请求应指向 https://<serviceHost>:<servicePort>/resolve...。

2. 验证业务请求

• 如果使用 TrustAPPHttpdnsHttpAdapter，观察抓包：
  • TCP 连接 IP 为 CDN 私有/边缘 IP。
  • HTTP Host 为原始域名。
  • TLS ClientHello 中 无 SNI 扩展。

8. 平台配置事项

• Android: 参照 Android SDK 文档配置混淆。
• iOS: 如果是手动集成 Flutter 插件，请确保 iOS 模块已包含依赖的静态库，并设置 Allow Arbitrary Loads (如果启用 HTTP)。

9. 常见问题

1. Flutter 端报错：NO_IP_AVAILABLE

• SDK 尚未解析出有效结果，请确认域名是否已在控制台添加并配置规则。

2. 请求报错：TLS_EMPTY_SNI_FAILED

• 仅支持 HTTPS 网站。如果所有 IP 尝试均失败，请检查网络权限及服务端防火墙。