waf-platform/HttpDNSSDK/docs/HTTPDNS SDK 集成文档（Android）.md

HTTPDNS SDK 集成文档（Android）

1. 版本与依赖

• SDK 模块：HttpDNSSDK/sdk/android/httpdns-sdk
• minSdkVersion：19
• targetSdkVersion：33
• compileSdk：33

将发布包中的 jar/aar 放到应用模块 libs/，在 app/build.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

import com.newsdk.sdk.android.httpdns.HttpDnsV1Client
import com.newsdk.sdk.android.httpdns.HttpDnsService

val service: HttpDnsService = HttpDnsV1Client.init(
    applicationContext,
    "your-app-id",
    "https://httpdns.example.com:8445", // serviceUrl，支持填写协议+端口
    "your-sign-secret" // 可传 ""
)

Java

import com.newsdk.sdk.android.httpdns.HttpDnsService;
import com.newsdk.sdk.android.httpdns.HttpDnsV1Client;

HttpDnsService service = HttpDnsV1Client.init(
        getApplicationContext(),
        "your-app-id",
        "https://httpdns.example.com:8445", // serviceUrl
        "your-sign-secret" // 可传 ""
);

4. 解析域名获取 CDN IP

Kotlin

import com.newsdk.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

import com.newsdk.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。

import com.newsdk.sdk.android.httpdns.HttpDnsV1Client
import com.newsdk.sdk.android.httpdns.network.HttpDnsAdapterOptions
import com.newsdk.sdk.android.httpdns.network.HttpDnsAdapterRequest

val adapter = HttpDnsV1Client.buildHttpClientAdapter(
    service,
    HttpDnsAdapterOptions.Builder()
        .setConnectTimeoutMillis(3000)
        .setReadTimeoutMillis(5000)
        .setRequestIpType(com.newsdk.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. 预解析与常用接口

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

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

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

7. 验证建议

1. 验证 /resolve

• 抓包看目标应为 https://<serviceUrl>/resolve...（即初始化时传入的 URL）

2. 验证业务请求（若使用 HttpDnsHttpAdapter）

• 目标地址应是 CDN IP
• HTTP Host 应为原域名
• TLS ClientHello 不应携带 SNI（No-SNI）

8. 混淆配置

-keep class com.newsdk.sdk.android.** { *; }

9. 常见问题

1. HTTPDNS 没生效

• 检查是否真正使用了 SDK 返回 IP（或用了 HttpDnsHttpAdapter）
• 检查失败回退逻辑是否总是直接走了系统 DNS

2. 使用 HttpDnsHttpAdapter 仍失败

• 只支持 HTTPS URL

3. 线上不要开启不安全证书

• HttpDnsAdapterOptions.Builder#setAllowInsecureCertificatesForDebugOnly(true) 仅限调试环境