本文主要介绍了客户端接入 HTTPDNS 的基本原理和主要步骤说明。
1. 前言
HTTPDNS 是一种端侧 DNS 解决方案，可替代传统 Local DNS，避免出现域名劫持、解析延迟、失败率高以及调度不精准等问题，为移动终端提供更稳定、更快速、更安全的解析能力。接入 HTTPDNS 总共包括以下几个主要步骤：
开通服务
添加域名到解析列表
获取开发配置
获取解析 IP
应用解析结果到网络库
接入成功验证
如果您使用了软件自定义解析实现业务调度，还需要配置自定义解析策略，参考自定义解析
其中，前三步属于控制台操作，如果您还没完成对应操作，可以参考产品使用流程。后三步属于客户端接入流程。本文主要介绍 客户端接入流程，在展开之前，我们先了解下 DNS 解析器。
2. DNS解析器
DNS 解析器是一种负责接收用户域名查询请求，并返回对应 IP 地址的网络服务组件。当 App 客户端 发起网络请求时，通常会先调用其内部集成的 网络库（如 NSURLSession、OkHttp、libcurl 等）。网络库在建立连接前，会通过 DNS 解析器将目标域名解析为 IP 地址，以便后续完成 TCP/UDP 连接。DNS 解析器可以分为两类：
系统 DNS 解析器：由操作系统提供并维护的域名解析组件（库或系统服务）。应用通过统一 API 调用（如 POSIX
getaddrinfo()、WindowsDnsQuery()、AppleNetwork.framework等）触发系统解析器完成域名解析。系统解析器会依据当前网络配置（如本地 hosts 文件、DNS 缓存、网络适配器配置）发起查询，最终向递归 DNS 服务器请求解析结果。这些递归 DNS 服务器通常由 DHCP 自动下发的运营商 DNS，或者用户手动配置的公共 DNS（如 8.8.8.8、1.1.X.X）提供服务，并返回对应的 IP 地址。自定义 DNS 解析器：由应用或第三方库实现的、部分或完全绕过系统解析器的解析逻辑。应用可直接绕过运营商下发的递归 DNS，改为访问指定的解析服务（如 HTTPDNS 服务器），获取权威解析结果IP。常见方式包括：应用接管网络库的 DNS 接口（如 OkHttp 的
Dns接口、libcurl 的resolve机制），在应用层直接注入解析结果；或者通过代理方式接管请求流量，在代理层完成 DNS Hook 与域名到 IP 的映射，从而实现定制化的域名解析与连接调度。
客户端接入 HTTPDNS 的过程，就是基于 HTTPDNS 服务实现自定义 DNS 解析器的过程，下图以一个 HTTP 请求为例，演示客户端如何通过自定义 DNS 解析器 或 DoH 协议，将 HTTPDNS 服务端返回的解析结果应用到网络库中，确保网络请求使用最优 IP 建立连接。
3. 接入流程
在开通服务和在控制台添加域名到解析域名列表后，就可以通过HTTPDNS实现自定义 DNS 解析器，主要包含三个核心步骤：
获取解析 IP ：访问 HTTPDNS 服务端获取域名对应的 IP 地址
应用解析结果 ：将获取的 IP 地址注入到网络库的请求中
接入成功验证：通过日志、网络抓包等方式确认以上两步生效
3.1 获取解析IP
您可以通过 SDK、HTTP API 和 DoH 三种方式从 HTTPDNS 服务端获取域名解析结果：
若需快速接入并屏蔽与服务端的交互复杂度，同时获得完整的高可用与性能优化能力，建议优先使用 SDK接入
若环境限制无法引入 SDK 或需要高度定制控制，则选择 HTTP API接入，它支持HTTP协议、更轻量，并可扩展如 加密、加签、SDNS 及额外错误码的能力
若客户端网络库封闭（如基于 Chromium 内核的 CEF、Electron、Qt WebEngine 等），暴露网络层的 API 有限，但开放了 DoH 配置接口，则推荐使用 DoH接入
在绝大多数场景下，推荐优先选择 SDK 方案。
3.2 应用解析结果
获取解析 IP 之后，您需要把该 IP 应用到网络请求的 DNS 解析环节，应用方案取决于您所使用的网络库是否支持自定义 DNS 解析。如果网络库提供 DNS Hook 或域名映射接口，可直接注入解析结果；若未提供，则需通过 IP 直连、协议替换或本地代理等方式进行适配。本文档同时列出了常用网络库和框架的适配方案，供参考。
Android：OkHttp、Webview、ExoPlayer、HttpURLConnection、阿里云OSS SDK等
iOS：Native网络库、WebView、阿里云OSS SDK等
HarmonyOS：阿里云OSS SDK、Network Kit 和 RCP等
跨平台：Flutter框架最佳实践、Unity框架最佳实践等
说明Socket.io、HttpClient、Glide、SwiftNIO、AFNetworking、Alamofire、Libcurl 等其他网络库或框架的适配方案，请联系技术支持咨询。
3.3 接入成功验证
客户端接入 HTTPDNS 后，建议通过以下两种方式进行验证以上两个步骤是否接入成功：
日志验证（推荐）
方式：在客户端埋点打印，从 HTTPDNS API 获取的解析 IP 列表和实际业务请求是否正常发起。
特点：该方式实现简单、轻量级，适合绝大多数场景。
劫持模拟：
通过将手机WIFI网络的 DNS 服务器设置为一个无效地址，观察业务请求是否依然能够正常发起，以此判断HTTPDNS是否接入成功。
特点：该方式能够有效屏蔽系统 DNS 干扰，更加准确。
4. 总结
接入 HTTPDNS 的本质是基于 HTTPDNS 构建自定义 DNS 解析器。本文简要介绍了获取解析 IP、应用到网络库以及接入验证三个核心步骤。更多接入细节、 API 说明和注意事项，请参见对应接入方式的用户手册。SDK 接入参考SDK接入，HTTP API接入参考HTTP API接入，DoH接入参考DoH接入手册。