带阿里标识的版本

EdgeHttpDNS/iOS SDK集成文档.md

@@ -0,0 +1,124 @@
+# 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` 字段匹配。