sdk final

2026-03-05 16:53:59 +08:00
parent a10f3f3740
commit 491ade1bc3
44 changed files with 1595 additions and 960 deletions
--- a/集成文档（iOS）.md
+++ b/集成文档（iOS）.md
@@ -0,0 +1,115 @@
+# HTTPDNS SDK 集成文档（iOS）
+
+## 一、 准备工作
+1. **获取配置**：登录控制台，获取您的 `AppId` 和 `apiUrl`。
+2. **环境要求**：支持 iOS 12.0 及以上版本。
+3. **网络权限**：确保应用具有访问互联网的权限。
+
+---
+
+## 二、 安装配置（手动集成）
+由于本版本分发的是二进制编译产物，请按照以下步骤集成：
+
+1. **导入框架**：将解压得到的 `NewHttpDNS.xcframework` 文件夹拖入您的 Xcode 工程中。在弹出的对话框中勾选 "Copy items if needed"。
+2. **配置 Target**：在项目的 `General` -> `Frameworks, Libraries, and Embedded Content` 中，确保 `NewHttpDNS.xcframework` 的 Embed 属性设置为 **Do Not Embed** (因为它是静态库封装)。
+3. **添加系统依赖**：在 `Build Phases` -> `Link Binary With Libraries` 中添加以下系统库：
+    - `Foundation.framework`
+    - `CFNetwork.framework`
+    - `SystemConfiguration.framework`
+    - `CoreTelephony.framework`
+    - `libsqlite3.tbd`
+    - `libresolv.tbd`
+    - `libz.tbd`
+
+---
+
+## 三、 快速入门
+
+### 1. 初始化 SDK
+在 `AppDelegate` 或应用启动位置进行初始化。建议导入统一头文件 `<NewHttpDNS/NewHttpDNS.h>`。
+
+```objective-c
+#import <NewHttpDNS/NewHttpDNS.h>
+
+// 推荐在应用启动时初始化
+HttpdnsEdgeService *service = [[HttpdnsEdgeService alloc] initWithAppId:@"YOUR_APP_ID"
+                                                                 apiUrl:@"https://YOUR_API_URL:PORT"
+                                                             signSecret:@"YOUR_SIGN_SECRET"];
+```
+
+### 2. 域名解析
+调用 `resolveHost` 方法获取域名的解析结果。
+
+```objective-c
+[service resolveHost:@"www.example.com" 
+           queryType:@"A" // A 为 IPv4，AAAA 为 IPv6
+          completion:^(HttpdnsEdgeResolveResult * _Nullable result, NSError * _Nullable error) {
+    if (result) {
+        NSLog(@"解析成功，IPs: %@", result.ipv4s);
+        NSLog(@"TTL: %ld", (long)result.ttl);
+    } else {
+        NSLog(@"解析失败: %@", error.localizedDescription);
+    }
+}];
+```
+
+---
+
+## 四、 企业级业务接入（关键）
+
+针对 HTTPS 业务请求，SDK 提供了自动化的“IP直连 + SNI绕过”方案。
+
+### 业务请求方法
+使用 `requestURL` 接口，它会自动处理解析、IP 尝试、TLS 握手及证书校验。
+
+```objective-c
+NSURL *targetUrl = [NSURL URLWithString:@"https://api.example.com/data"];
+[service requestURL:targetUrl
+             method:@"GET"
+            headers:@{@"User-Agent": @"MyApp/1.0"}
+               body:nil
+         completion:^(NSData * _Nullable data, NSHTTPURLResponse * _Nullable response, NSError * _Nullable error) {
+    if (!error) {
+        NSLog(@"请求成功，状态码: %ld", (long)response.statusCode);
+    }
+}];
+```
+
+---
+
+## 五、 核心原理说明
+
+### SNI 绕过与证书校验
+在传统的 IP 直连方案中，直接访问 IP 会导致 TLS 握手缺失 SNI 字段，从而引发服务器证书校验失败。
+
+**SDK 内部处理逻辑：**
+1. **IP 映射**：将请求 URL 替换为解析出的 IP。
+2. **Host 复原**：在 HTTP 请求头中强行注入原始域名作为 `Host`。
+3. **TLS 校验优化**：SDK 修改了系统的 `SecPolicy`。在验证证书时，指示系统不仅校验连接的 IP，还要校验证书上的通用名称（CN）或使用者备用名称（SAN）是否与原始域名匹配。
+4. **全链路加密**：即便在不发送 SNI 的情况下，依然保证了数据传输的加密性与身份验证的真实性。
+
+---
+
+## 六、 API 参考
+
+### HttpdnsEdgeService 方法集
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+| `initWithAppId:...` | `appId`, `apiUrl`, `signSecret` | 执行 SDK 初始化，`apiUrl` 需包含协议和端口。 |
+| `resolveHost:queryType:completion:` | `host`, `qtype`, `callback` | 异步请求解析，`qtype` 仅支持 "A" 或 "AAAA"。 |
+| `requestURL:...` | `url`, `method`, `headers`, `body`, `callback` | **推荐**。一站式业务请求，内置调度与 SSL 优化。 |
+| `setLogEnabled:` | `BOOL` | 控制控制台详细日志输出，建议仅调试阶段开启。 |
+
+---
+
+## 七、 常见问题 (FAQ)
+
+**Q: 是否支持双栈（IPv4 & IPv6）并发解析？**
+A: 后端接口单次仅支持一种类型。建议在业务层发起两次 `resolveHost` 请求（A 和 AAAA），并在本地进行竞速或优先级排序。
+
+**Q: 为什么返回 400 错误？**
+A: 请检查 `qtype` 参数。目前严格区分大小写，务必传入 `"A"` 或 `"AAAA"`，暂不支持其他别名。
+
+**Q: 手动集成后运行崩溃，报错 Symbol not found?**
+A: 请检查“系统依赖记录”是否已添加 `libsqlite3.tbd` 等必需库。