125 lines
4.2 KiB
Markdown
125 lines
4.2 KiB
Markdown
# iOS SDK 集成文档（Edge HTTPDNS）
|
||
|
||
## 1. 版本与依赖
|
||
|
||
- SDK 模块：`HttpDNSSDK/sdk/ios/NewHttpDNS`
|
||
- 支持系统：iOS 11.0+
|
||
- 集成方式：
|
||
- **CocoaPods**：在 `Podfile` 中添加 `pod 'NewHTTPDNS', :path => 'path/to/sdk/ios'`
|
||
- **手动集成**：将 `NewHttpDNS` 源码或编译后的静态库导入项目，并添加依赖的系统库（Foundation, CFNetwork, SystemConfiguration）。
|
||
|
||
## 2. SNI 行为说明（关键）
|
||
|
||
1. **/resolve 请求链路**（SDK -> 你的 HTTPDNS 服务域名）
|
||
- 使用标准 HTTPS 请求。
|
||
- 默认携带 SNI（用于通过 WAF/CDN 识别服务域名）。
|
||
|
||
2. **业务请求链路**（拿到 CDN IP 后通过 `HttpdnsEdgeService` 发起业务 HTTPS）
|
||
- **IP 直连 + No-SNI**：SDK 会建立与 IP 的连接，并将 `NSURLRequest` 的 `URL` 替换为 IP，同时保留 `Host` 头部为原域名。
|
||
- **证书校验**：由于清空了 SNI，常规 SNI 校验会跳过，需确保后端节点支持 Host 匹配证书。
|
||
|
||
## 3. 初始化 SDK（推荐用 EdgeService 封装）
|
||
|
||
### Objective-C
|
||
|
||
```objective-c
|
||
#import <NewHttpDNS/HttpdnsEdgeService.h>
|
||
|
||
HttpdnsEdgeService *service = [[HttpdnsEdgeService alloc] initWithAppId:@"your-app-id"
|
||
primaryServiceHost:@"httpdns.example.com"
|
||
backupServiceHost:@"httpdns-backup.example.com"
|
||
servicePort:443
|
||
signSecret:@"your-sign-secret"];
|
||
```
|
||
|
||
### Swift
|
||
|
||
```swift
|
||
import NewHttpDNS
|
||
|
||
let service = HttpdnsEdgeService(appId: "your-app-id",
|
||
primaryServiceHost: "httpdns.example.com",
|
||
backupServiceHost: "httpdns-backup.example.com",
|
||
servicePort: 443,
|
||
signSecret: "your-sign-secret")
|
||
```
|
||
|
||
## 4. 解析域名获取 CDN IP
|
||
|
||
### Objective-C
|
||
|
||
```objective-c
|
||
[service resolveHost:@"api.example.com"
|
||
queryType:@"A"
|
||
completion:^(HttpdnsEdgeResolveResult * _Nullable result, NSError * _Nullable error) {
|
||
if (result) {
|
||
NSLog(@"IPv4s: %@", result.ipv4s);
|
||
NSLog(@"TTL: %ld", (long)result.ttl);
|
||
}
|
||
}];
|
||
```
|
||
|
||
### Swift
|
||
|
||
```swift
|
||
service.resolveHost("api.example.com", queryType: "A") { result, error in
|
||
if let ips = result?.ipv4s {
|
||
print("Resolved IPs: \(ips)")
|
||
}
|
||
}
|
||
```
|
||
|
||
## 5. 业务请求接入方式
|
||
|
||
使用 `HttpdnsEdgeService` 提供的 `requestURL` 方法，自动处理 IP 直连与 SNI 隐藏。
|
||
|
||
### Objective-C
|
||
|
||
```objective-c
|
||
NSURL *url = [NSURL URLWithString:@"https://api.example.com/path?x=1"];
|
||
[service requestURL:url
|
||
method:@"GET"
|
||
headers:@{@"Custom-Header": @"Value"}
|
||
body:nil
|
||
completion:^(NSData * _Nullable data, NSHTTPURLResponse * _Nullable response, NSError * _Nullable error) {
|
||
if (!error) {
|
||
NSLog(@"Status Code: %ld", (long)response.statusCode);
|
||
// 处理 data
|
||
}
|
||
}];
|
||
```
|
||
|
||
### Swift
|
||
|
||
```swift
|
||
let url = URL(string: "https://api.example.com/path?x=1")!
|
||
service.requestURL(url, method: "GET", headers: ["Custom-Header": "Value"], body: nil) { data, response, error in
|
||
if let resp = response {
|
||
print("Status Code: \(resp.statusCode)")
|
||
}
|
||
}
|
||
```
|
||
|
||
## 6. 验证建议
|
||
|
||
1. **验证 /resolve**
|
||
- 观察网络请求，应指向 `https://httpdns.example.com/resolve?appId=...&dn=...`。
|
||
- 确认返回 JSON 包含 `code: "SUCCESS"`。
|
||
|
||
2. **验证业务请求**
|
||
- 确认请求握手阶段不携带 SNI 扩展。
|
||
- 确认请求的 TCP 连接目标为解析出的私有 IP/CDN IP。
|
||
|
||
## 7. 常见问题
|
||
|
||
1. **编译报错：找不到头文件**
|
||
- 请确认 `Header Search Paths` 包含 SDK 路径。
|
||
- 如果使用 CocoaPods，请确保执行 `pod install` 并打开 `.xcworkspace`。
|
||
|
||
2. **请求返回 403 (Sign Invalid)**
|
||
- 确认控制台已开启“签名校验”，且本地传入的 `signSecret` 与控制台一致。
|
||
- 确认系统时间正常（差值超过 30s 可能导致签名失效）。
|
||
|
||
3. **HTTPS 证书验证失败**
|
||
- 检查 `HttpdnsEdgeService` 是否能正确匹配证书，通常是在 No-SNI 模式下通过 `Host` 字段匹配。
|