165 lines
5.8 KiB
Markdown
165 lines
5.8 KiB
Markdown
# 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` 中引用：
|
||
|
||
```yaml
|
||
dependencies:
|
||
new_httpdns:
|
||
path: ./packages/new_httpdns
|
||
```
|
||
|
||
### 2. Android 配置（必须）
|
||
|
||
在 Android 项目的 `android/settings.gradle.kts` 中，添加插件内嵌的本地 Maven 仓库：
|
||
|
||
```kotlin
|
||
dependencyResolutionManagement {
|
||
repositories {
|
||
maven { url = uri("../packages/new_httpdns/android/libs/repo") } // 路径与插件实际位置对应
|
||
google()
|
||
mavenCentral()
|
||
// ...
|
||
}
|
||
}
|
||
```
|
||
|
||
> 路径为相对于 `android/` 目录的路径，请根据 `new_httpdns` 插件的实际放置位置调整。
|
||
|
||
### 3. 执行更新
|
||
在终端运行：
|
||
```bash
|
||
flutter pub get
|
||
```
|
||
|
||
---
|
||
|
||
## 三、 快速入门
|
||
|
||
### 1. 初始化 SDK
|
||
在 `main()` 函数中完成初始化工作。初始化分两步：先调用 `init()` 配置参数，再调用 `build()` 启动 SDK。
|
||
|
||
```dart
|
||
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. 域名解析
|
||
```dart
|
||
// 同步非阻塞获取缓存（推荐）
|
||
var result = await TrustAPPHttpdns.resolveHostSyncNonBlocking("www.example.com");
|
||
List<String> ipv4s = result['ipv4'];
|
||
```
|
||
|
||
---
|
||
|
||
## 四、 最佳实践：自动化业务请求
|
||
|
||
在 Flutter 中，证书校验通常较为复杂。我们为此专门开辟了 `HttpAdapter` 方案。
|
||
|
||
### 使用内置 Adapter
|
||
通过 `createHttpAdapter` 创建的实例，会自动处理域名解析、IP 直连及手动校验证书逻辑。
|
||
|
||
```dart
|
||
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`，该选项仅供调试使用。
|
||
|
||
```dart
|
||
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`）中开启明文传输权限。
|