# iOS SDK 集成文档（Edge HTTPDNS）

## 1. 版本与依赖

- SDK 模块：`EdgeHttpDNS/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` 字段匹配。