134 lines
3.6 KiB
Markdown
134 lines
3.6 KiB
Markdown
# Flutter SDK 集成文档（Edge HTTPDNS）
|
||
|
||
## 1. 版本与依赖
|
||
|
||
- SDK 插件：`EdgeHttpDNS/sdk/flutter/new_httpdns`
|
||
- 环境要求：Flutter 2.15+ / Dart 2.15+
|
||
|
||
在 `pubspec.yaml` 中引用本地插件：
|
||
|
||
```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
|
||
|
||
```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
|
||
|
||
```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
|
||
|
||
```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. 其他常用接口
|
||
|
||
```dart
|
||
// 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 尝试均失败，请检查网络权限及服务端防火墙。
|