客户端 SDK 的解析记录缓存机制
最近更新时间：2023.09.01 12:28:40
首次发布时间：2023.09.01 12:28:40
本文档介绍火山引擎移动解析（HTTPDNS）客户端 SDK 的解析记录缓存机制。您可以对缓存机制进行自定义配置。
预解析
SDK 初始化时，SDK 按照预解析域名列表发起批量预解析。预解析完成之后，SDK 会把解析记录写入客户端缓存。
SDK 在连接到另一个网络时，也会按照预解析域名列表发起批量解析。
App 调用 SDK 的解析方法发起域名解析请求时，如果 SDK 在客户端缓存找到了匹配的解析记录，SDK 就可以直接返回该记录。这样就可以降低移动解析 HTTPDNS 的解析请求耗时。
说明
您可以通过以下方法设置预解析域名列表：
- Android：
IHttpDnsDepend接口的 getPreloadDomains 方法：在初始化之前设置预解析域名列表。HttpDNS类的 setPreloadHosts 方法：在初始化之后设置预解析域名列表。
- iOS：
- TTDnsResolver 类 的 preloadDomains 属性：在初始化之前或之后设置预解析域名列表。
- iOS SDK 暂不支持在初始化之后设置预解析域名列表。
说明
您可以通过以下方法设置 SDK 在连接到另一个网络时，是否会按照预解析域名列表发起批量解析。
解析请求过程
以 HTTPDNS 服务端的解析结果优先时的解析请求过程
如果 SDK 以 HTTPDNS 服务端的解析结果优先，解析过程中的缓存机制如下。
如上图所示，App 调用允许查询缓存的解析方法时：
SDK 首先会查询客户端缓存是否有来自 HTTPDNS 服务端的解析记录。
如果客户端缓存中有来自 HTTPDNS 服务端的解析记录，SDK 会检查解析记录是否过期。如果解析记录没有过期，或解析记录已过期但还在过期容忍时间，SDK 会返回缓存中的解析记录。此时解析完成。
说明
SDK 默认允许使用过期的解析记录，但不是无限制使用。SDK 只会使用处于过期容忍时间内的解析记录。在默认情况下，过期容忍时间为 60 秒，即 SDK 只会使用过期之后 60 秒内的解析记录。
- 您可以通过 setUseStaleCache 方法（Android） 或 enableUseStaleCache 属性（iOS）设置是否允许使用过期的解析记录。
- 您可以通过 setHttpdnsStaleTime 方法（Android）或 overStaleCacheTimeIntervalAfterTTL 属性（iOS）设置过期解析记录的过期容忍时间。
如果解析记录过期但还在过期容忍时间内，SDK 会返回缓存中的解析记录。此时解析完成。
如果客户端缓存中没有来自 HTTPDNS 服务端的解析记录，或者解析记录过期且不在过期容忍时间内，SDK 同时进行以下任务：
- 向 HTTPDNS 服务端发送解析请求。
- 查询本地缓存中的 Local DNS 解析记录。如果缓存中的解析记录过期或没有匹配的解析记录，SDK 向 Local DNS 发送解析请求。
如果在等待解析结果超时前（默认是 5 秒），SDK 收到了来自 HTTPDNS 服务端的解析结果，则解析完成。
如果等待解析结果超时且 SDK 没有收到 HTTPDNS 服务端返回的解析结果，则 SDK 会检查是否获取了来自 Local DNS 的解析记录。如果 SDK 获取了来自 Local DNS 的解析记录，则解析完成。
说明
SDK 在查询来自 Local DNS 的缓存时，无论您是否设置了过期容忍时间，SDK 都不会使用缓存中过期的解析记录。
如果等待解析结果超时且 SDK 没有获取到 Local DNS 返回的解析结果，则 SDK 解析失败。SDK 会立即返回解析失败的信息。此时解析完成。
说明
SDK 会在后台继续等待解析结果。如果在解析请求超时前（默认是 15 秒），HTTPDNS 服务端或 Local DNS 返回了解析结果，SDK 会把解析结果写入客户端缓存。
在以 HTTPDNS 解析结果优先的解析过程中，等待解析结果超时时间与解析请求超时时间的区别如下：
| 超时时间类型 | 描述 | 设置方法 |
|---|---|---|
| 等待解析结果超时时间 | 等待解析结果超时时间是从SDK 发送解析请求开始，到 SDK 停止等待解析结果的时间。
| 默认的等待解析结果超时时间是 5 秒。 您可以通过 setHttpDnsPreferTime 方法（Android）或 firstTaskPreferTimeMs 属性（iOS）设置等待解析结果超时时间。 |
| 解析请求超时时间 | SDK 返回解析结果之后，还没有返回结果的解析请求还能继续在后台运行。解析请求超时时间是从 SDK 返回解析结果开始，到 SDK 停止等待在后台运行的解析请求返回解析结果的时间。 如果 SDK 在解析请求超时时间内收到解析结果，则 SDK 会把解析结果写入本地缓存。 | 默认的请求超时时间是 15 秒。 您可以通过 setHttpDnsRequestTimeout 方法（Android） 或 setHttpDnsRequestTimeout 方法（iOS）设置解析请求超时时间。 |
以 Local DNS 的解析结果优先时的解析请求过程
以 Local DNS 解析结果优先的解析过程与以 HTTPDNS 解析结果优先的解析过程基本类似，主要区别在于 SDK 会首先查询来自 Local DNS 的解析结果。本文不再重复描述。
SDK 自动刷新缓存的过程
如下图所示，SDK 提供了自动刷新机制，可以保证缓存中解析记录总是有效的。这样，App 调用 SDK 发起解析请求时，SDK 可以返回缓存中的解析记录，从而降低 SDK 获取解析结果的时延。
有效缓存和过期缓存
解析记录是存在有效期（TTL）的。SDK 将解析记录写入客户端缓存之后，如果解析记录过期，您可以通过设置过期容忍时间继续使用过期的解析记录。过期容忍时间可以提高缓存的命中率，从而降低 SDK 发送解析请求的耗时。
说明
- setUseStaleCache 方法（Android）和 enableUseStaleCache 属性（iOS）可以设置 SDK 是否使用缓存中的过期解析记录。SDK 默认使用缓存中的过期解析记录。
- setHttpdnsStaleTime 方法（Android）或 overStaleCacheTimeIntervalAfterTTL 属性（iOS）可以设置过期解析记录的过期容忍时间。过期容忍时间默认为 60 秒。
例如，您的 SDK 使用了默认设置。SDK 向 HTTPDNS 服务端发送解析请求，获得了一条解析记录。该解析记录的有效期（TTL）是 20 秒。SDK 会把该解析记录写入客户端缓存。SDK 获得解析记录 20 秒后，该解析记录过期。此时，该解析记录还处于过期容忍时间。SDK 获得解析记录 80 秒后，该解析记录超过了过期容忍时间。
SDK 如何自动刷新缓存
SDK 会根据以下逻辑刷新解析记录：
- 如果解析记录过期并且已经达到了过期容忍时间后，列表中的记录数量还没有达到指定数量，则 SDK 会单独刷新该解析记录。
- 如果列表中的记录数量达到了指定数量时，解析记录还没有达到过期容忍时间，则 SDK 会批量刷新列表中的记录。
说明
- enableRefreshStaleCache 方法（Android）和 enableAutoRefreshStaleCache 属性（iOS）可以开启或关闭客户端缓存中解析记录的自动刷新。SDK 默认开启客户端缓存中解析记录的自动刷新。
- 在开启自动刷新的前提下，enableBatchRefresh 方法（Android）和 enableAutoRefreshWithHosts 属性 可以开启或关闭批量刷新。SDK 默认开启批量刷新。