# HTTPDNS SDK 集成文档（Android）

## 一、 准备工作
1. **获取参数**：从控制台获取您的 `AppId`、`apiUrl` 和 `secretKey`（可选）。
2. **系统要求**：Android 5.0 (API Level 21) 及以上。
3. **网络要求**：应用需要具备 `INTERNET` 与 `ACCESS_NETWORK_STATE` 权限。

---

## 二、 安装配置

### 1. 导入 AAR/Jar
将 SDK 发行包中的 `.aar` 文件复制到您 Android 工程的 `libs/` 目录下。

### 2. 配置 build.gradle
在 App 模块的 `build.gradle` 中添加依赖引用：

```gradle
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
    // SDK 内部可能需要的系统库支持
    implementation 'androidx.annotation:annotation:1.5.0'
}
```

### 3. 配置权限 (AndroidManifest.xml)
```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

---

## 三、 快速入门

### 1. 初始化 SDK
推荐在自定义 `Application` 的 `onCreate` 中初始化，确保全局可用。

```java
// 建立配置
InitConfig config = new InitConfig.Builder()
    .setContext(context)
    .setServiceUrl("https://httpdns.example.com:8445") // 统一配置协议、Host与端口
    .setSecretKey("your_secret_key") // 如果开启了签名校验
    .setEnableCacheIp(true) // 开启持久化缓存
    .setEnableExpiredIp(true) // 允许使用过期 IP（秒开优化）
    .buildFor("your_app_id");

// 获取服务实例
HttpDnsService service = HttpDns.getService(context, "your_app_id");
```

### 2. 域名解析
使用异步非阻塞接口获取 IP。

```java
service.getHttpDnsResultForHostSyncNonBlocking("www.example.com", RequestIpType.v4);
// 或者使用更详细的异步回调
```

---

## 四、 企业级业务接入

SDK 并不强制要求修改您的请求框架（如 OkHttp），但强烈建议在拦截器中集成。

### 1. IP 直连原理
1. 通过 `getHttpDnsResultForHostSyncNonBlocking` 获取 IP。
2. 将请求 URL 中的 Host 替换为 IP。
3. 设置 HTTP 请求头中的 `Host` 字段为原始域名。

### 2. HTTPS 证书校验（针对 SNI）
当使用 IP 直连访问 HTTPS 时，需要自定义 `HostnameVerifier`。

```java
OkHttpClient client = new OkHttpClient.Builder()
    .hostnameVerifier((hostname, session) -> {
        // 自定义校验逻辑：验证当前请求的 IP 证书是否匹配原始业务域名
        return OkHostnameVerifier.INSTANCE.verify("api.example.com", session);
    })
    .build();
```

---

## 五、 API 参考手册

| 方法名 | 说明 |
| :--- | :--- |
| `setServiceUrl(String)` | **核心**。通过 URL 一站式配置服务地址，自动处理 Scheme 和 Port。 |
| `setEnableCacheIp(boolean)` | 启用持久化缓存，进程重启后能立即从磁盘读取上一次的解析结果。 |
| `setPreResolveHosts(List)` | 预解析域名列表。建议将首屏需要的关键域名在此配置，大幅度提升首屏加载速度。 |
| `setLogEnabled(boolean)` | 全局 Log 控制，开启后可通过 Logcat 观察 SDK 的详细调度逻辑。 |

---

## 六、 核心原理

### 为什么我们更安全？
Android 原生 DNS 解析极其依赖 `InetAddress`，而此方法通过系统的 `getaddrinfo` 实现，极其容易被运营商拦截或重定向。
我们的 SDK 采用私有 HTTP 协议层，并配合 **HMAC-SHA256 签名机制**（如果配置了 secretKey），确保从域名解析到业务请求的每一环都是经过身份校验且不可篡改的。

---

## 七、 常见问题 (FAQ)

**Q: 如何处理 IPv6 环境？**
A: 初始化时无需特殊设置。请求解析时传入 `RequestIpType.both`，SDK 会尝试同时解析 A 和 AAAA 记录，并根据当前网络环境返回最优结果。

**Q: AAR 编译报错：Duplicate Class?**
A: 请确保 libs 下没有重复版本的 SDK，并检查是否重复引入了某些兼容包。

**Q: 日志里看到 "HTTPDNS resolve failed"，该如何排查？**
A: 1. 检查 `apiUrl` 是否可直接通过浏览器/Curl 访问。 2. 检查 `AppId` 是否正确。 3. 检查手机系统时间是否正确（如果开启了签名防伪）。