curl/libcurl 的 CURLOPT_DNS_CACHE_TIMEOUTDNS 缓存生命周期控制与底层实现剖析【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl导读CURLOPT_DNS_CACHE_TIMEOUT是 libcurl 中用于控制主机名解析结果DNS 缓存条目在内存中保留时长的核心选项。它直接决定了一次域名解析结果能被多少个连接复用、在多少秒内不被重新查询是调整连接建立速度、减少 DNS 查询压力、以及规避临时性解析故障的重要旋钮。读完本文你将掌握该选项的完整语义默认 60 秒、0禁用、-1永久缓存、三种取值边界下的行为差异并能够结合 lib/vdns/dnscache.c 与 lib/setopt.c 的源码理解其修剪、负缓存与容量上限等底层机制进而在真实业务中做出正确的配置决策。选项总览作用、原型与适用协议CURLOPT_DNS_CACHE_TIMEOUT在官方文档中的定义为 life-time for DNS cache entriesDNS 缓存条目的生存时间其接口原型如下见 docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md#include curl/curl.h CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_CACHE_TIMEOUT, long age);参数类型long单位为秒设置的是缓存超时时间。适用协议全部All。无论走 HTTP、HTTPS、FTP、SMTP 还是其他协议只要涉及主机名到地址的解析该选项都生效。引入版本Added-in 7.9.3即从 2001 年发布的 curl 7.9.3 起便存在属于历史悠久的稳定选项。默认值60秒见文档DEFAULT一节。在选项注册表中它被登记为CURLOT_LONG类型见 lib/easyoptions.c即接受一个长整型数值。三种取值模式默认、禁用与永久缓存文档对参数的语义描述非常明确传入一个 long 值表示缓存超时的秒数名称解析结果会被保存在内存中并在该秒数内被复用。三种典型取值对应三种截然不同的行为模式取值行为适用场景按文档建议引申60默认解析结果在内存中保留 60 秒绝大多数常规场景默认即合理0完全禁用缓存每次连接都重新解析域名频繁变更、需要实时感知 DNS 变化的场景代价是每次连接多一次解析开销-1缓存条目永久保留永不因超时被修剪长期运行且域名固定的应用可显著减少重复解析但要注意缓存可能长期持有过期地址值得强调的是-1只是不因超时被修剪并不代表条目永远不会被删除——文档明确指出当缓存条目数超过 30,000 时libcurl 无论如何都会执行修剪该行为自 8.1.0 起加入。源码视角选项如何进入 libcurl 内部理解该选项的底层语义需要从参数入口开始追踪。1. setopt 入口秒转毫秒与 -1 的特殊处理在 lib/setopt.c 中CURLOPT_DNS_CACHE_TIMEOUT的处理逻辑为case CURLOPT_DNS_CACHE_TIMEOUT: if(arg ! -1) return setopt_set_timeout_sec(s-dns_cache_timeout_ms, arg); s-dns_cache_timeout_ms -1; break;这段代码揭示了两个关键事实-1是特例只有精确传入-1才会将内部字段直接置为-1表示永久缓存而其他任何非负值都走setopt_set_timeout_sec路径。内部以毫秒存储setopt_set_timeout_sec见 lib/setopt.c会把传入的秒数乘以 1000 转换为毫秒后存入data-set.dns_cache_timeout_ms并做了溢出保护当秒数超过TIMEDIFF_T_MAX / 1000时直接钳制为TIMEDIFF_T_MAX。因此如果你传入一个负数如-5而不是-1setopt_set_timeout_sec会返回CURLE_BAD_FUNCTION_ARGUMENT拒绝该参数——只有-1这个特定值才表示永久。内部存储字段定义于 lib/urldata.htimediff_t dns_cache_timeout_ms; /* DNS cache timeout (milliseconds) */。2. 默认值的初始化默认值 60 秒在 lib/url.c 中以毫秒形式初始化set-dns_cache_timeout_ms 60000; /* Timeout every 60 seconds by default */这与文档中DEFAULT 60的声明完全一致也再次印证了选项对外是秒、对内是毫秒的设计。3. 缓存的实际存放位置解析结果并非存在 easy handle 上而是存放在共享层级结构中。从 lib/vdns/dnscache.c 的dnscache_get()可以看出优先顺序static struct Curl_dnscache *dnscache_get(struct Curl_easy *data) { if(data-share >void Curl_dnscache_prune(struct Curl_easy *data) { struct Curl_dnscache *dnscache dnscache_get(data); /* the timeout may be set -1 (forever) */ timediff_t timeout_ms >if(dns (data-set.dns_cache_timeout_ms ! -1)) { ... if(dnscache_entry_is_stale(user, dns)) { infof(data, Hostname in DNS cache was stale, zapped); dns NULL; Curl_hash_delete(dnscache-entries, key.data, key.len); } }这确保了即使两次修剪之间间隔较长应用也绝不会使用超龄的缓存地址——命中过期条目会被立即zap删除并触发一次新的解析。同时注意-1模式下此检查同样被跳过缓存条目会一直被信任。负缓存失败解析也进缓存自 curl 8.16.0 起失败的名称解析也会被写入 DNS 缓存但只保留设定超时时间的一半自 8.22.0 起该行为进一步收紧——只有解析器明确回答域名不存在NXDOMAIN时才会缓存失败结果瞬时性或本地解析器故障不会被缓存。这一点在源码中有两处呼应负缓存条目的写入入口为Curl_dnscache_add_negative()见 lib/vdns/dnscache.c在过期判定dnscache_entry_is_stale()中无地址条目负缓存的年龄会被加倍计算if(!dns-addr) age * 2; /* negative entries age twice as fast */见 lib/vdns/dnscache.c。年龄翻倍意味着负缓存条目会以正常条目两倍的速度老化配合只保留一半超时时间的策略实际效果就是失败结果比成功结果更快失效避免一次瞬时故障长时间阻塞后续请求。为什么不建议随意修改文档与源码共同给出的警告文档在 DESCRIPTION 中给出了明确建议除非绝对必要否则不要修改该选项。其理由在源码与系统层面都能找到依据大值导致缓存膨胀如果超时时间内访问了大量不同主机名缓存条目会显著增多。虽然 30,000 条上限兜底但在达到上限前内存占用与哈希遍历开销都会上升。文档特别提醒使用大值时要小心。libc 解析函数不主动重读服务器信息文档指出多数 libc 的解析函数如res_init(3)涉及的底层机制在被显式通知之前不会重新读取名称服务器配置。即使 DHCP 更新了 DNS 服务器信息libcurl 可能仍在使用旧服务器——这在表象上很像DNS 缓存问题实则是系统解析层的行为单纯调整本选项无法解决。TTL 无关性DNS 记录本身带有 TTL生存时间属性但 libcurl不使用 TTL。文档明确说明该缓存超时完全是一种推测性设计——假设一个名字在未来一小段时间内仍解析到相同地址。因此把超时设得比权威 TTL 更长也不会自动纠正只会持有更久的旧地址。实战示例控制短生命周期域名的解析时效官方文档给出的示例见 docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md展示了如何在代码中把缓存窗口压到极短int main(void) { CURL *curl curl_easy_init(); if(curl) { CURLcode result; curl_easy_setopt(curl, CURLOPT_URL, https://example.com/foo.bin); /* only reuse addresses for a short time */ curl_easy_setopt(curl, CURLOPT_DNS_CACHE_TIMEOUT, 2L); result curl_easy_perform(curl); /* in this second request, the cache is not be used if more than two seconds have passed since the previous name resolve */ result curl_easy_perform(curl); curl_easy_cleanup(curl); } }该示例的两个要点将超时设为2L秒后第一次curl_easy_perform()解析的地址只会被复用约 2 秒若两次请求间隔超过 2 秒第二次请求会触发全新的名称解析源码层面表现为fetch_addr()中该条目被判 stale 并删除。这一模式适合域名记录变更频繁、希望客户端尽快感知新地址的场景。注意若curl_easy_init()失败返回 NULL示例中直接跳过设置——这也是 libcurl 编程的常规防御写法。返回值与错误处理文档的RETURN VALUE一节说明curl_easy_setopt()返回CURLcode指示成功或失败CURLE_OK0表示一切正常非零表示发生错误具体错误码可参考libcurl-errors(3)。从源码看该选项可能返回的错误包括CURLE_BAD_FUNCTION_ARGUMENT传入-1以外的负数例如-5由setopt_set_timeout_sec()的if(secs 0)分支触发见 lib/setopt.c其余合法取值任意非负 long 或-1均返回CURLE_OK。与相关选项的协同关系该选项并非孤立存在官方文档的 See-also 列表见 docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md 头部元数据指向了完整的相关能力矩阵CURLOPT_CONNECTTIMEOUT_MS连接超时与 DNS 缓存协同决定建立连接的总耗时上限CURLOPT_DNS_SERVERS指定使用的 DNS 服务器影响解析结果来源CURLOPT_DNS_USE_GLOBAL_CACHE全局共享缓存开关注意其默认关闭与本文所述的 multi/share 级缓存机制相关联CURLOPT_MAXAGE_CONN连接复用的最大存活时间控制的是连接而非解析结果的复用窗口CURLOPT_RESOLVE手动指定主机名到地址的映射可视为对缓存内容的直接注入CURLMOPT_NETWORK_CHANGED通知 multi 句柄网络环境已变化配合Curl_dnscache_clear()见 lib/vdns/dnscache.c可主动清空缓存。实践中常见的组合思路是对动态环境移动网络、容器 IP 频繁漂移将CURLOPT_DNS_CACHE_TIMEOUT调小或配合网络变更通知主动清缓存对地址长期稳定的内部服务则可适度放大缓存窗口以降低解析延迟与 DNS 服务器压力。但无论哪种取向都应遵循文档的忠告——在明确需求的前提下再动这个选项并在大值场景下持续观察缓存规模。小结CURLOPT_DNS_CACHE_TIMEOUT虽是一个单一 long 参数的简单选项其背后却串联起 libcurl 的名称解析缓存体系的全部关键环节秒级 API 与毫秒级内部存储的转换、-1永久模式与0禁用模式的特殊分支、multi/share 级的共享缓存、基于时间戳的修剪与惰性过期检查、30,000 条容量上限的强制收敛以及 8.16.0/8.22.0 之后引入的负缓存半衰期策略。理解了这些源码层面的实现你就能在减少 DNS 查询与及时感知地址变化之间做出有依据的权衡而不是盲目调大或调小这个看似不起眼的超时值。【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
curl/libcurl 的 CURLOPT_DNS_CACHE_TIMEOUT：DNS 缓存生命周期控制与底层实现剖析
curl/libcurl 的 CURLOPT_DNS_CACHE_TIMEOUTDNS 缓存生命周期控制与底层实现剖析【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl导读CURLOPT_DNS_CACHE_TIMEOUT是 libcurl 中用于控制主机名解析结果DNS 缓存条目在内存中保留时长的核心选项。它直接决定了一次域名解析结果能被多少个连接复用、在多少秒内不被重新查询是调整连接建立速度、减少 DNS 查询压力、以及规避临时性解析故障的重要旋钮。读完本文你将掌握该选项的完整语义默认 60 秒、0禁用、-1永久缓存、三种取值边界下的行为差异并能够结合 lib/vdns/dnscache.c 与 lib/setopt.c 的源码理解其修剪、负缓存与容量上限等底层机制进而在真实业务中做出正确的配置决策。选项总览作用、原型与适用协议CURLOPT_DNS_CACHE_TIMEOUT在官方文档中的定义为 life-time for DNS cache entriesDNS 缓存条目的生存时间其接口原型如下见 docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md#include curl/curl.h CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_CACHE_TIMEOUT, long age);参数类型long单位为秒设置的是缓存超时时间。适用协议全部All。无论走 HTTP、HTTPS、FTP、SMTP 还是其他协议只要涉及主机名到地址的解析该选项都生效。引入版本Added-in 7.9.3即从 2001 年发布的 curl 7.9.3 起便存在属于历史悠久的稳定选项。默认值60秒见文档DEFAULT一节。在选项注册表中它被登记为CURLOT_LONG类型见 lib/easyoptions.c即接受一个长整型数值。三种取值模式默认、禁用与永久缓存文档对参数的语义描述非常明确传入一个 long 值表示缓存超时的秒数名称解析结果会被保存在内存中并在该秒数内被复用。三种典型取值对应三种截然不同的行为模式取值行为适用场景按文档建议引申60默认解析结果在内存中保留 60 秒绝大多数常规场景默认即合理0完全禁用缓存每次连接都重新解析域名频繁变更、需要实时感知 DNS 变化的场景代价是每次连接多一次解析开销-1缓存条目永久保留永不因超时被修剪长期运行且域名固定的应用可显著减少重复解析但要注意缓存可能长期持有过期地址值得强调的是-1只是不因超时被修剪并不代表条目永远不会被删除——文档明确指出当缓存条目数超过 30,000 时libcurl 无论如何都会执行修剪该行为自 8.1.0 起加入。源码视角选项如何进入 libcurl 内部理解该选项的底层语义需要从参数入口开始追踪。1. setopt 入口秒转毫秒与 -1 的特殊处理在 lib/setopt.c 中CURLOPT_DNS_CACHE_TIMEOUT的处理逻辑为case CURLOPT_DNS_CACHE_TIMEOUT: if(arg ! -1) return setopt_set_timeout_sec(s-dns_cache_timeout_ms, arg); s-dns_cache_timeout_ms -1; break;这段代码揭示了两个关键事实-1是特例只有精确传入-1才会将内部字段直接置为-1表示永久缓存而其他任何非负值都走setopt_set_timeout_sec路径。内部以毫秒存储setopt_set_timeout_sec见 lib/setopt.c会把传入的秒数乘以 1000 转换为毫秒后存入data-set.dns_cache_timeout_ms并做了溢出保护当秒数超过TIMEDIFF_T_MAX / 1000时直接钳制为TIMEDIFF_T_MAX。因此如果你传入一个负数如-5而不是-1setopt_set_timeout_sec会返回CURLE_BAD_FUNCTION_ARGUMENT拒绝该参数——只有-1这个特定值才表示永久。内部存储字段定义于 lib/urldata.htimediff_t dns_cache_timeout_ms; /* DNS cache timeout (milliseconds) */。2. 默认值的初始化默认值 60 秒在 lib/url.c 中以毫秒形式初始化set-dns_cache_timeout_ms 60000; /* Timeout every 60 seconds by default */这与文档中DEFAULT 60的声明完全一致也再次印证了选项对外是秒、对内是毫秒的设计。3. 缓存的实际存放位置解析结果并非存在 easy handle 上而是存放在共享层级结构中。从 lib/vdns/dnscache.c 的dnscache_get()可以看出优先顺序static struct Curl_dnscache *dnscache_get(struct Curl_easy *data) { if(data-share >void Curl_dnscache_prune(struct Curl_easy *data) { struct Curl_dnscache *dnscache dnscache_get(data); /* the timeout may be set -1 (forever) */ timediff_t timeout_ms >if(dns (data-set.dns_cache_timeout_ms ! -1)) { ... if(dnscache_entry_is_stale(user, dns)) { infof(data, Hostname in DNS cache was stale, zapped); dns NULL; Curl_hash_delete(dnscache-entries, key.data, key.len); } }这确保了即使两次修剪之间间隔较长应用也绝不会使用超龄的缓存地址——命中过期条目会被立即zap删除并触发一次新的解析。同时注意-1模式下此检查同样被跳过缓存条目会一直被信任。负缓存失败解析也进缓存自 curl 8.16.0 起失败的名称解析也会被写入 DNS 缓存但只保留设定超时时间的一半自 8.22.0 起该行为进一步收紧——只有解析器明确回答域名不存在NXDOMAIN时才会缓存失败结果瞬时性或本地解析器故障不会被缓存。这一点在源码中有两处呼应负缓存条目的写入入口为Curl_dnscache_add_negative()见 lib/vdns/dnscache.c在过期判定dnscache_entry_is_stale()中无地址条目负缓存的年龄会被加倍计算if(!dns-addr) age * 2; /* negative entries age twice as fast */见 lib/vdns/dnscache.c。年龄翻倍意味着负缓存条目会以正常条目两倍的速度老化配合只保留一半超时时间的策略实际效果就是失败结果比成功结果更快失效避免一次瞬时故障长时间阻塞后续请求。为什么不建议随意修改文档与源码共同给出的警告文档在 DESCRIPTION 中给出了明确建议除非绝对必要否则不要修改该选项。其理由在源码与系统层面都能找到依据大值导致缓存膨胀如果超时时间内访问了大量不同主机名缓存条目会显著增多。虽然 30,000 条上限兜底但在达到上限前内存占用与哈希遍历开销都会上升。文档特别提醒使用大值时要小心。libc 解析函数不主动重读服务器信息文档指出多数 libc 的解析函数如res_init(3)涉及的底层机制在被显式通知之前不会重新读取名称服务器配置。即使 DHCP 更新了 DNS 服务器信息libcurl 可能仍在使用旧服务器——这在表象上很像DNS 缓存问题实则是系统解析层的行为单纯调整本选项无法解决。TTL 无关性DNS 记录本身带有 TTL生存时间属性但 libcurl不使用 TTL。文档明确说明该缓存超时完全是一种推测性设计——假设一个名字在未来一小段时间内仍解析到相同地址。因此把超时设得比权威 TTL 更长也不会自动纠正只会持有更久的旧地址。实战示例控制短生命周期域名的解析时效官方文档给出的示例见 docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md展示了如何在代码中把缓存窗口压到极短int main(void) { CURL *curl curl_easy_init(); if(curl) { CURLcode result; curl_easy_setopt(curl, CURLOPT_URL, https://example.com/foo.bin); /* only reuse addresses for a short time */ curl_easy_setopt(curl, CURLOPT_DNS_CACHE_TIMEOUT, 2L); result curl_easy_perform(curl); /* in this second request, the cache is not be used if more than two seconds have passed since the previous name resolve */ result curl_easy_perform(curl); curl_easy_cleanup(curl); } }该示例的两个要点将超时设为2L秒后第一次curl_easy_perform()解析的地址只会被复用约 2 秒若两次请求间隔超过 2 秒第二次请求会触发全新的名称解析源码层面表现为fetch_addr()中该条目被判 stale 并删除。这一模式适合域名记录变更频繁、希望客户端尽快感知新地址的场景。注意若curl_easy_init()失败返回 NULL示例中直接跳过设置——这也是 libcurl 编程的常规防御写法。返回值与错误处理文档的RETURN VALUE一节说明curl_easy_setopt()返回CURLcode指示成功或失败CURLE_OK0表示一切正常非零表示发生错误具体错误码可参考libcurl-errors(3)。从源码看该选项可能返回的错误包括CURLE_BAD_FUNCTION_ARGUMENT传入-1以外的负数例如-5由setopt_set_timeout_sec()的if(secs 0)分支触发见 lib/setopt.c其余合法取值任意非负 long 或-1均返回CURLE_OK。与相关选项的协同关系该选项并非孤立存在官方文档的 See-also 列表见 docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md 头部元数据指向了完整的相关能力矩阵CURLOPT_CONNECTTIMEOUT_MS连接超时与 DNS 缓存协同决定建立连接的总耗时上限CURLOPT_DNS_SERVERS指定使用的 DNS 服务器影响解析结果来源CURLOPT_DNS_USE_GLOBAL_CACHE全局共享缓存开关注意其默认关闭与本文所述的 multi/share 级缓存机制相关联CURLOPT_MAXAGE_CONN连接复用的最大存活时间控制的是连接而非解析结果的复用窗口CURLOPT_RESOLVE手动指定主机名到地址的映射可视为对缓存内容的直接注入CURLMOPT_NETWORK_CHANGED通知 multi 句柄网络环境已变化配合Curl_dnscache_clear()见 lib/vdns/dnscache.c可主动清空缓存。实践中常见的组合思路是对动态环境移动网络、容器 IP 频繁漂移将CURLOPT_DNS_CACHE_TIMEOUT调小或配合网络变更通知主动清缓存对地址长期稳定的内部服务则可适度放大缓存窗口以降低解析延迟与 DNS 服务器压力。但无论哪种取向都应遵循文档的忠告——在明确需求的前提下再动这个选项并在大值场景下持续观察缓存规模。小结CURLOPT_DNS_CACHE_TIMEOUT虽是一个单一 long 参数的简单选项其背后却串联起 libcurl 的名称解析缓存体系的全部关键环节秒级 API 与毫秒级内部存储的转换、-1永久模式与0禁用模式的特殊分支、multi/share 级的共享缓存、基于时间戳的修剪与惰性过期检查、30,000 条容量上限的强制收敛以及 8.16.0/8.22.0 之后引入的负缓存半衰期策略。理解了这些源码层面的实现你就能在减少 DNS 查询与及时感知地址变化之间做出有依据的权衡而不是盲目调大或调小这个看似不起眼的超时值。【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考