# 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` 等必需库。