HTTPDNS SDK 集成文档（iOS）

一、准备工作

获取配置：登录控制台，获取您的 AppId 和 apiUrl。
环境要求：支持 iOS 12.0 及以上版本。
网络权限：确保应用具有访问互联网的权限。

二、安装配置（手动集成）

由于本版本分发的是二进制编译产物，请按照以下步骤集成：

导入框架：将解压得到的 NewHttpDNS.xcframework 文件夹拖入您的 Xcode 工程中。在弹出的对话框中勾选 "Copy items if needed"。
配置 Target：在项目的 General -> Frameworks, Libraries, and Embedded Content 中，确保 NewHttpDNS.xcframework 的 Embed 属性设置为 Do Not Embed (因为它是静态库封装)。
添加系统依赖：在 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>。

#import <NewHttpDNS/NewHttpDNS.h>

// 推荐在应用启动时初始化
HttpdnsEdgeService *service = [[HttpdnsEdgeService alloc] initWithAppId:@"YOUR_APP_ID"
                                                                 apiUrl:@"https://YOUR_API_URL:PORT"
                                                             signSecret:@"YOUR_SIGN_SECRET"];

2. 域名解析

调用 resolveHost 方法获取域名的解析结果。

[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 握手及证书校验。

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 内部处理逻辑：

IP 映射：将请求 URL 替换为解析出的 IP。
Host 复原：在 HTTP 请求头中强行注入原始域名作为 Host。
TLS 校验优化：SDK 修改了系统的 SecPolicy。在验证证书时，指示系统不仅校验连接的 IP，还要校验证书上的通用名称（CN）或使用者备用名称（SAN）是否与原始域名匹配。
全链路加密：即便在不发送 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 等必需库。

4.6 KiB Raw Blame History Unescape Escape

HTTPDNS SDK 集成文档（iOS）

一、 准备工作

二、 安装配置（手动集成）

三、 快速入门