165 lines
4.2 KiB
Markdown
165 lines
4.2 KiB
Markdown
# HTTPDNS SDK 集成文档（Android）
|
||
|
||
## 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)` 仅限调试环境 |