sdk final

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

@@ -0,0 +1,119 @@
+# 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. 执行更新
+在终端运行：
+```bash
+flutter pub get
+```
+
+---
+
+## 三、 快速入门
+
+### 1. 初始化 SDK
+在 `main()` 函数中完成初始化工作。
+
+```dart
+import 'package:new_httpdns/new_httpdns.dart';
+
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  
+  bool success = await TrustAPPHttpdns.init(
+    appId: "your-app-id",
+    apiUrl: "https://your-api-url:8445", // 请包含协议与端口
+    secretKey: "your-sign-secret" // 如果开启了安全签名
+  );
+  
+  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. **安全绕过**：通过自定义 `badCertificateCallback` 并在内部手动验证证书的真伪性（验证其 SAN/CN），确保在没有 SNI 的情况下依然是可信的 HTTPS 连接。
+
+---
+
+## 六、 API 全集参考
+
+| 接口名 | 功能说明 |
+| :--- | :--- |
+| `init` | **核心**。一站式初始化配置。 |
+| `resolveHostSyncNonBlocking` | 立即从本地缓存读取。若缓存未命中则触发后台更新。 |
+| `setPreResolveHosts` | 建议在启动后设置，提前加载核心业务域名的 IP。 |
+| `setPersistentCacheIPEnabled` | 设置开启/关闭 IP 记录的磁盘持久化缓存。 |
+| `createHttpAdapter` | 生成业务请求工具类，自动绕过运营商劫持。 |
+| `setLogEnabled` | 开发者调试模式开关。 |
+
+---
+
+## 七、 常见问题 (FAQ)
+
+**Q: 插件是否全平台通用？**
+A: 目前该插件仅针对 iOS 和 Android。在 Web 或 Desktop 端运行会抛出 `unimplemented` 错误，建议结合 `kIsWeb` 等进行环境判断。
+
+**Q: 如何处理解析超时？**
+A: `TrustAPPHttpdnsAdapterOptions` 中可配置 `connectTimeoutMs`。默认 3000ms。
+
+**Q: 如果 API 地址是 HTTP 的怎么办？**
+A: 强烈建议生产环境使用 HTTPS。如果测试环境必须用 HTTP，请在两端的原生配置文件（`Info.plist` / `AndroidManifest.xml`）中开启明文传输权限。