waf-platform/HttpDNSSDK/docs/iOS SDK集成文档.md

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

#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

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

[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

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

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

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 字段匹配。