@alicloud-emas/httpdns-react-native

阿里云 HTTPDNS React Native 插件，封装 Android 和 iOS 原生 HTTPDNS SDK，并提供统一的 JavaScript API。接入后，可以在 React Native 应用中完成 HTTPDNS 初始化、缓存、预解析、IP 优选等能力配置。

插件会接入 React Native 网络请求链路。业务侧继续使用原有 fetch、XMLHttpRequest，以及默认基于 React Native 网络模块的 Axios 请求方式即可，无需手动调用解析接口，也无需自行适配 OkHttp、NSURLSession 等原生网络库。

使用前请先开通 HTTPDNS 服务，并在控制台获取 AccountId。如果需要使用鉴权解析或加密解析，请同时准备 SecretKey 或 AESSecretKey。

安装

在 React Native 项目根目录执行：

npm install @alicloud-emas/httpdns-react-native

如果使用 Yarn：

yarn add @alicloud-emas/httpdns-react-native

Android 配置

Android 端无需额外原生代码配置。

插件会通过 ContentProvider 在应用启动早期自动注入 React Native 网络模块使用的 OkHttpClient，并配置自定义 DNS 解析器。业务侧继续使用原有网络请求代码即可。

如果 React Native 应用的 Android release 包开启了代码压缩或混淆（例如 minifyEnabled true），请在应用工程的 android/app/proguard-rules.pro 中添加：

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

iOS 配置

配置 CocoaPods 源

HTTPDNS iOS SDK 和 EMASCurl 发布在阿里云 CocoaPods 源中，请在 iOS 工程的 Podfile 顶部添加：

source 'https://github.com/aliyun/aliyun-specs.git'
source 'https://github.com/CocoaPods/Specs.git'

然后执行：

cd ios
pod install

注入 React Native 网络链路

iOS 端需要在 AppDelegate.m 或 AppDelegate.mm 中调用一次安装方法：

#import <httpdns-react-native/AliyunHttpDnsRN.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  [AliyunHttpDnsRN install];

  // 其他 React Native 初始化代码
  return YES;
}

该方法会通过 RCTSetCustomNSURLSessionConfigurationProvider 为 React Native 网络请求注入 HTTPDNS。

初始化和使用

插件采用先配置、后初始化的模式。以下配置建议在调用 init 前设置，init 内部会统一应用这些配置并构建 HTTPDNS 服务实例。

import * as AliyunHttpDns from '@alicloud-emas/httpdns-react-native';

AliyunHttpDns.setLogEnabled(true);
AliyunHttpDns.setHttpsRequestEnabled(true);
AliyunHttpDns.setReuseExpiredIPEnabled(true);

await AliyunHttpDns.init({
  accountId: 123456,
  secretKey: 'your_secret_key', // 可选，开启鉴权解析时配置
});

初始化完成后，可以配置热点域名预解析，减少后续请求的解析时延：

AliyunHttpDns.setPreResolveHosts(['www.aliyun.com'], 'auto');

之后业务侧继续使用原有 React Native 网络请求方式即可：

import axios from 'axios';

// 使用 fetch
const response = await fetch('https://www.aliyun.com');
const text = await response.text();

// 使用 Axios
const axiosResponse = await axios.get('https://www.aliyun.com');

注意事项

1. Android 端通过 ContentProvider 自动注入 React Native 网络模块使用的 OkHttpClient，无需修改 MainApplication，也无需手动适配 OkHttp。

2. iOS 端需要在 AppDelegate 中调用 [AliyunHttpDnsRN install]。插件会通过 EMASCurl 接入 React Native 网络链路，关于 EMASCurl 的能力，请参考 EMASCurl。

3. 插件在网络请求链路中默认使用同步非阻塞解析：优先返回缓存结果；缓存未命中或无可用结果时，不会长时间阻塞业务请求。

API

init

构建 HTTPDNS 服务实例。请确保在使用 HTTPDNS 能力前完成初始化，建议在应用启动阶段调用。React Native 插件会在初始化时将已设置的配置项统一应用到底层 Android/iOS HTTPDNS SDK。

const success = await AliyunHttpDns.init({
  accountId: 123456,
  secretKey: 'your_secret_key', // 可选，开启鉴权解析时配置
  aesSecretKey: 'your_aes_secret_key', // 可选，开启加密解析时配置
});

参数：

| 参数名 | 类型 | 是否必须 | 说明 | | --- | --- | --- | --- | | accountId | number | 必选 | HTTPDNS 账号 ID | | secretKey | string | 可选 | 鉴权密钥 | | aesSecretKey | string | 可选 | 加密密钥 |

返回值：

| 类型 | 说明 | | --- | --- | | Promise<boolean> | true 表示初始化成功，false 表示初始化失败 |

setLogEnabled

本地调试日志开关。可以开启调试日志排查解析相关问题，上线时建议关闭。

AliyunHttpDns.setLogEnabled(true);

setHttpsRequestEnabled

设置 SDK 内部向服务端发起解析请求时，是否使用 HTTPS 协议。若不调用该接口，默认使用 HTTP 协议。

AliyunHttpDns.setHttpsRequestEnabled(true);

setPersistentCacheIPEnabled

设置是否启用持久化缓存。持久化缓存功能用于优化启动后的域名解析环节耗时，进而提升首屏加载速度。

开启后，HTTPDNS 会将上一次解析到的结果保存到本地持久层。App 重启后，每个域名首次解析会优先从持久层获取缓存结果，以实现更快的解析效率。

AliyunHttpDns.setPersistentCacheIPEnabled(true);
AliyunHttpDns.setPersistentCacheIPEnabled(true, 86400);

参数：

| 参数名 | 类型 | 是否必须 | 说明 | | --- | --- | --- | --- | | enabled | boolean | 必选 | 是否开启持久化缓存 | | discardExpiredAfterSeconds | number | 可选 | App 启动后，从本地持久化缓存加载记录到内存缓存时，丢弃过期时间已经超过该时长的记录，单位秒 |

setReuseExpiredIPEnabled

设置是否允许解析接口返回 TTL 过期的缓存解析结果。

开启后，SDK 在缓存过期时可以先返回已过期的缓存 IP，以减少 DNS 环节处理时间，并刷新该域名的解析结果。

AliyunHttpDns.setReuseExpiredIPEnabled(true);

setPreResolveAfterNetworkChanged

设置网络环境变化后，是否自动刷新域名解析结果。

当设备网络变化时，SDK 会监听网络变化事件并根据策略处理缓存。开启该功能后，SDK 会在网络切换后自动刷新解析结果，降低域名解析环节耗时，进而提升请求性能。

AliyunHttpDns.setPreResolveAfterNetworkChanged(true);

setRegion

设置 HTTPDNS 启动服务节点。如果 App 需要在海外环境使用 HTTPDNS，可以主动设置启动服务节点。设置后，SDK 会使用该节点进行域名解析和后续调度节点列表更新。

AliyunHttpDns.setRegion('cn');

取值包括：cn、hk、sg、de、us。默认无需设置，SDK 内部会根据客户端网络进行调度。

setTimeoutInterval

设置域名解析请求超时时间，单位为秒。该配置只影响 HTTPDNS SDK 向服务端发起的解析请求，不影响业务网络请求的超时时间。

AliyunHttpDns.setTimeoutInterval(2);

setIPRankingList

启用 IP 优选。指定域名对应服务的探测端口后，SDK 会对相应域名解析返回的 IP 列表进行 TCP 建连测速，并根据测速结果对 IP 列表进行动态排序。

首次触发 HTTPDNS 解析后立即获得的 IP 列表可能未经排序。该能力适用于对连接时延敏感的域名，启用前建议结合业务流量和服务端负载情况评估。

AliyunHttpDns.setIPRankingList({
  'www.aliyun.com': 443,
});

configCacheTtlChanger

自定义解析结果 TTL。HTTPDNS SDK 默认使用域名解析结果中携带的 TTL 值作为缓存时间。通过该接口可以根据不同域名指定 TTL，从而改变 SDK 对解析结果的缓存时间。

AliyunHttpDns.configCacheTtlChanger({
  'www.aliyun.com': 300,
});

setPreResolveHosts

设置预解析域名列表。在 App 启动并完成 SDK 初始化后，可以调用此接口设置后续可能会使用到的热点域名，以便 SDK 提前解析，减少后续域名解析时请求的时延。

如果在运行过程中调用，SDK 也会立即解析设置的域名列表，从而刷新这些域名的解析结果并记录到缓存中。

AliyunHttpDns.setPreResolveHosts(['www.aliyun.com'], 'auto');

参数：

| 参数名 | 类型 | 是否必须 | 说明 | | --- | --- | --- | --- | | hosts | string[] | 必选 | 预解析域名列表 | | ipType | string | 可选 | auto、ipv4、ipv6、both，默认 auto |

hosts 中应传入纯域名字符串，不要包含协议头、路径或端口。

getSessionId

获取当前 HTTPDNS 会话 ID。该 ID 可用于问题排查和日志关联。

const sessionId = await AliyunHttpDns.getSessionId();

返回值：

| 类型 | 说明 | | --- | --- | | Promise<string | null> | 当前会话 ID，未初始化或获取失败时返回 null |

cleanHostCache

清除域名缓存。传入域名列表时，清除指定域名的缓存；不传参数或传入空数组时，清除全部域名缓存。

// 清除全部缓存
AliyunHttpDns.cleanHostCache();

// 清除指定域名缓存
AliyunHttpDns.cleanHostCache(['www.aliyun.com']);

setAuthCurrentTime

校正 App 签名时间。鉴权模式下，如果设备时间不准确，可能导致鉴权校验不通过。调用该接口后，SDK 会根据传入时间校正后续请求的签名时间。

校正操作在 App 的一个生命周期内生效，App 重启后需要重新设置。

const currentTime = Math.floor(Date.now() / 1000);
AliyunHttpDns.setAuthCurrentTime(currentTime);

参数 time 为 Unix 时间戳，单位为秒。