# Android SDK 集成文档（Edge HTTPDNS）

## 1. 版本与依赖

- SDK 模块：`EdgeHttpDNS/sdk/android/httpdns-sdk`
- `minSdkVersion`：19
- `targetSdkVersion`：33
- `compileSdk`：33

将发布包中的 `jar/aar` 放到应用模块 `libs/`，在 `app/build.gradle` 中添加：

```gradle
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
    implementation 'androidx.appcompat:appcompat:1.6.1'
}
```

## 2. SNI 行为说明（关键）

当前 SDK 行为与代码一致：

1. `/resolve` 请求链路（SDK -> 你的 HTTPDNS 服务域名）
- 走域名 HTTPS
- 默认 TLS 行为（会带 SNI）

2. 业务请求链路（拿到 CDN IP 后发起业务 HTTPS）
- 使用 `HttpDnsHttpAdapter`：按 IP 建连，`Host` 保留原域名，并清空 SNI（No-SNI）

## 3. 初始化 SDK（推荐用 V1 客户端）

### Kotlin

```kotlin
import com.new.sdk.android.httpdns.HttpDnsV1Client
import com.new.sdk.android.httpdns.HttpDnsService

val service: HttpDnsService = HttpDnsV1Client.init(
    context = applicationContext,
    appId = "your-app-id",
    primaryServiceHost = "httpdns.example.com",
    backupServiceHost = "httpdns-backup.example.com", // 可空字符串
    servicePort = 443,
    signSecret = "your-sign-secret" // 可空字符串
)
```

### Java

```java
import com.new.sdk.android.httpdns.HttpDnsService;
import com.new.sdk.android.httpdns.HttpDnsV1Client;

HttpDnsService service = HttpDnsV1Client.init(
        getApplicationContext(),
        "your-app-id",
        "httpdns.example.com",
        "httpdns-backup.example.com", // 可传 ""
        443,
        "your-sign-secret" // 可传 ""
);
```

## 4. 解析域名获取 CDN IP

### Kotlin

```kotlin
import com.new.sdk.android.httpdns.HTTPDNSResult

val result: HTTPDNSResult = HttpDnsV1Client.resolveHost(
    service = service,
    host = "api.example.com",
    qtype = "A",   // "A" 或 "AAAA"
    cip = null      // 可选，客户端 IP 透传
)

val ips = result.ips ?: emptyArray()
```

### Java

```java
import com.new.sdk.android.httpdns.HTTPDNSResult;

HTTPDNSResult result = HttpDnsV1Client.resolveHost(
        service,
        "api.example.com",
        "A",
        null
);

String[] ips = result.getIps();
```

## 5. 业务请求接入方式

#使用 `HttpDnsHttpAdapter`（IP 直连 + No-SNI）

业务请求侧做“隐匿 SNI”。该适配器仅支持 HTTPS URL。

```kotlin
import com.new.sdk.android.httpdns.HttpDnsV1Client
import com.new.sdk.android.httpdns.network.HttpDnsAdapterOptions
import com.new.sdk.android.httpdns.network.HttpDnsAdapterRequest

val adapter = HttpDnsV1Client.buildHttpClientAdapter(
    service,
    HttpDnsAdapterOptions.Builder()
        .setConnectTimeoutMillis(3000)
        .setReadTimeoutMillis(5000)
        .setRequestIpType(com.new.sdk.android.httpdns.RequestIpType.auto)
        .build()
)

val req = HttpDnsAdapterRequest(
    "GET",
    "https://api.example.com/path?x=1"
)

val resp = adapter.execute(req)
val code = resp.statusCode
val bodyBytes = resp.body
val usedIp = resp.usedIp
```

## 6. 预解析与常用接口

```kotlin
service.setPreResolveHosts(listOf("api.example.com", "img.example.com"))

val r1 = service.getHttpDnsResultForHostSync("api.example.com", com.new.sdk.android.httpdns.RequestIpType.auto)
val r2 = service.getHttpDnsResultForHostSyncNonBlocking("api.example.com", com.new.sdk.android.httpdns.RequestIpType.auto)
```

- `Sync`：允许阻塞等待刷新结果（上限受 timeout 等配置影响）
- `NonBlocking`：快速返回当前可用缓存/结果，不阻塞等待

## 7. 验证建议

1. 验证 `/resolve`
- 抓包看目标应为 `https://<serviceHost>:<servicePort>/resolve...`

2. 验证业务请求（若使用 `HttpDnsHttpAdapter`）
- 目标地址应是 CDN IP
- HTTP `Host` 应为原域名
- TLS ClientHello 不应携带 SNI（No-SNI）

## 8. 混淆配置

```proguard
-keep class com.new.sdk.android.** { *; }
```

## 9. 常见问题

1. HTTPDNS 没生效
- 检查是否真正使用了 SDK 返回 IP（或用了 `HttpDnsHttpAdapter`）
- 检查失败回退逻辑是否总是直接走了系统 DNS

2. 使用 `HttpDnsHttpAdapter` 仍失败
- 只支持 HTTPS URL

3. 线上不要开启不安全证书
- `HttpDnsAdapterOptions.Builder#setAllowInsecureCertificatesForDebugOnly(true)` 仅限调试环境