merge

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

@@ -20,7 +20,24 @@ dependencies:
     path: ./packages/new_httpdns
 ```
 
-### 2. 执行更新
+### 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
@@ -31,20 +48,33 @@ flutter pub get
 ## 三、 快速入门
 
 ### 1. 初始化 SDK
-在 `main()` 函数中完成初始化工作。
+在 `main()` 函数中完成初始化工作。初始化分两步：先调用 `init()` 配置参数，再调用 `build()` 启动 SDK。
 
 ```dart
 import 'package:new_httpdns/new_httpdns.dart';
 
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
-  
-  bool success = await TrustAPPHttpdns.init(
+
+  // 第一步：配置参数
+  await TrustAPPHttpdns.init(
     appId: "your-app-id",
     apiUrl: "https://your-api-url:8445", // 请包含协议与端口
-    secretKey: "your-sign-secret" // 如果开启了安全签名
+    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());
 }
 ```
@@ -89,8 +119,16 @@ try {
 Flutter 的 `HttpClient` 默认会发送 SNI。当我们为了防劫持而使用 IP 直连时，服务器可能因为解析不出 SNI 域名而拒绝握手。
 
 **插件解决之道：**
-1. **Adapter 自动化**：插件内部会解析目标域名，并在连接 IP 成功后，通过 Dart 的底层 `HttpClient` 注入原始域名作为 `Host`。
-2. **安全绕过**：通过自定义 `badCertificateCallback` 并在内部手动验证证书的真伪性（验证其 SAN/CN），确保在没有 SNI 的情况下依然是可信的 HTTPS 连接。
+1. **Adapter 自动化**：插件内部会解析目标域名，并在连接 IP 成功后，通过 Dart 的底层 `HttpClient` 注入原始域名作为 `Host` 头，确保服务端正常响应。
+2. **证书校验**：默认情况下，`TrustAPPHttpdnsHttpAdapter` 会信任所有证书（适用于 IP 直连场景）。如需严格证书验证，请勿在生产环境启用 `allowInsecureCertificatesForDebugOnly`，该选项仅供调试使用。
+
+```dart
+final adapter = TrustAPPHttpdns.createHttpAdapter(
+  options: TrustAPPHttpdnsAdapterOptions(
+    allowInsecureCertificatesForDebugOnly: false, // 生产环境保持 false
+  ),
+);
+```
 
 ---
 
@@ -98,12 +136,19 @@ Flutter 的 `HttpClient` 默认会发送 SNI。当我们为了防劫持而使用
 
 | 接口名 | 功能说明 |
 | :--- | :--- |
-| `init` | **核心**。一站式初始化配置。 |
-| `resolveHostSyncNonBlocking` | 立即从本地缓存读取。若缓存未命中则触发后台更新。 |
-| `setPreResolveHosts` | 建议在启动后设置，提前加载核心业务域名的 IP。 |
-| `setPersistentCacheIPEnabled` | 设置开启/关闭 IP 记录的磁盘持久化缓存。 |
-| `createHttpAdapter` | 生成业务请求工具类，自动绕过运营商劫持。 |
-| `setLogEnabled` | 开发者调试模式开关。 |
+| `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` | 清除所有域名的本地缓存。 |
 
 ---