116 lines
4.6 KiB
Markdown
116 lines
4.6 KiB
Markdown
# 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` 等必需库。
|